Implement workspace provider resolver (resolve LLM keys, Tenderly, RPC from workspace_providers table)

[Hyperkit-dev]

🎯 Layer 1: Intent Parsing

What needs to be done?

Task Title:

Implement workspace provider resolver (resolve LLM keys, Tenderly, RPC from workspace_providers table)

Area: orchestration | Repos: services/ (Shannon-like)

Primary Goal:

Successfully implement workspace provider resolver (resolve LLM keys, Tenderly, RPC from workspace_providers table) with full functionality

User Story / Context:

As a platform user, I want the system to resolve workspace-specific provider configurations (LLM keys, Tenderly, RPC endpoints) from the database so that each workspace can use its own provider credentials

Business Impact:

Enables core platform functionality and multi-tenant workspace isolation. Supports the multi-tenant workspace model described in the Business Model

Task Metadata:

• Sprint: Sprint 1
• Related Epic/Project: GitHub Project 9 - Phase 1 Foundation
• Issue Type: Feature
• Area: Orchestration
• Related Documentation:
  • Platform Blueprint - Section 1: System overview (Core Services)
  • Scope Definition - MVP Scope: Sprint 1-2
  • Execution Strategy - Section 2: Architecture Document
  • Business Model - Pillar 1: HyperAgent Cloud (SaaS)

---

📚 Layer 2: Knowledge Retrieval

What information do I need?

Required Skills / Knowledge:

• Backend/API (FastAPI, Python)
• DevOps/Infra (CI/CD, Docker)

Estimated Effort:

M (Medium - 3-5 days)

Knowledge Resources:

• Review .cursor/skills/ for relevant patterns
• Check .cursor/llm/ for implementation examples
• Read Platform Blueprint: docs/draft.md
• Read Scope Definition: docs/planning/3-Scope-Definition.md
• Read Execution Strategy: docs/reference/spec/execute.md
• Study tech docs / ADRs in docs/adrs/ directory
• Review API / schema references for relevant services

Architecture Context:

According to the Platform Blueprint, HyperAgent uses Supabase (PostgreSQL) for relational data. The workspace provider resolver is part of the orchestration layer that manages multi-tenant workspace configurations.

System Architecture Diagram:

graph TB
    subgraph "Orchestration Service"
        API[FastAPI Gateway]
        Router[Agent Router]
        State[State Manager]
        Queue[Task Queue]
        ProviderResolver[Provider Resolver]
    end
    
    subgraph "External Services"
        DB[(Supabase<br/>workspace_providers)]
        Cache[(Redis)]
        VectorDB[(Pinecone)]
    end
    
    API --> Router
    Router --> State
    Router --> Queue
    Router --> ProviderResolver
    ProviderResolver --> DB
    State --> DB
    Queue --> Cache
    Router --> VectorDB

Loading

Code Examples & Patterns:
Provider Resolver Example:

from services.orchestrator.providers import ProviderResolver
from supabase import create_client

class ProviderResolver:
    def __init__(self, supabase_client):
        self.db = supabase_client
    
    async def resolve_llm_key(self, workspace_id: str, provider: str) -> str:
        """Resolve LLM API key for workspace"""
        result = self.db.table("workspace_providers").select("*").eq(
            "workspace_id", workspace_id
        ).eq("provider_type", "llm").eq("provider_name", provider).execute()
        
        if not result.data:
            raise ValueError(f"No {provider} key configured for workspace")
        
        # Decrypt the stored key
        return decrypt_key(result.data[0]["encrypted_config"])
    
    async def resolve_tenderly_config(self, workspace_id: str) -> dict:
        """Resolve Tenderly configuration for workspace"""
        result = self.db.table("workspace_providers").select("*").eq(
            "workspace_id", workspace_id
        ).eq("provider_type", "tenderly").execute()
        
        return result.data[0]["config"] if result.data else None

---

⚠️ Layer 3: Constraint Analysis

What constraints and dependencies exist?

Known Dependencies:

• Workspace provider schema must be designed (see issue Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273)
• Supabase database must be set up with workspace_providers table

Technical Constraints:

Out of scope: Frontend UI changes (track separately). Focus on backend resolver implementation.

Current Blockers:

None identified (update as work progresses)

Risk Assessment & Mitigations:

Complex state management; use LangGraph best practices, add comprehensive tests. Ensure proper encryption/decryption of sensitive provider keys.

Resource Constraints:

• Deadline: Feb 5–17
• Effort Estimate: M (Medium - 3-5 days)

---

💡 Layer 4: Solution Generation

How should this be implemented?

Solution Approach:

Implement a ProviderResolver service in services/orchestrator/providers/resolver.py that:

1. Queries workspace_providers table for provider configurations
2. Handles encryption/decryption of sensitive keys
3. Provides methods for resolving LLM keys, Tenderly config, RPC endpoints
4. Implements caching for frequently accessed providers
5. Handles errors gracefully with proper fallbacks

Design Considerations:

• Follow established patterns from .cursor/skills/
• Maintain consistency with existing codebase
• Consider scalability and maintainability
• Ensure proper error handling
• Plan for testing and validation
• Implement proper encryption for sensitive data
• Add caching layer for performance
• Align with multi-tenant workspace model from Business Model

Acceptance Criteria (Solution Validation):

• ProviderResolver class implemented
• resolve_llm_key() method working
• resolve_tenderly_config() method working
• resolve_rpc_endpoint() method working
• Encryption/decryption of sensitive keys working
• Caching layer implemented
• Error handling for missing providers
• Unit tests written and passing
• Integration tests passing
• Error handling implemented
• Code reviewed and approved
• Documentation updated

---

📋 Layer 5: Execution Planning

What are the concrete steps?

Implementation Steps:

1. Review workspace provider schema from issue Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273
2. Design ProviderResolver class interface
3. Implement database query methods
4. Implement encryption/decryption logic
5. Implement caching layer
6. Implement error handling and fallbacks
7. Write unit tests
8. Write integration tests
9. Update docs (README, runbook, in-app help, etc.)
10. Demo in sprint review and gather feedback

Environment Setup:
Repos / Services:

• Backend repo: hyperagent/services/orchestrator/
• Infra / IaC repo: hyperagent/infra/

Required Environment Variables:

• DATABASE_URL= (get from internal vault)
• REDIS_URL= (get from internal vault)
• ANTHROPIC_API_KEY= (get from internal vault)
• OPENAI_API_KEY= (get from internal vault)
• GEMINI_API_KEY= (get from internal vault)
• ENCRYPTION_KEY= (get from internal vault)

Access & Credentials:

• API keys: Internal vault (1Password / Doppler)
• Access request: Contact @devops or project lead

---

✅ Layer 6: Output Formatting & Validation

How do we ensure quality delivery?

Ownership & Collaboration:

• Owner: @JustineDevs
• Reviewer: @ArhonJay
• Access Request: @JustineDevs or @ArhonJay
• Deadline: Feb 5–17
• Communication: Daily stand-up updates, GitHub issue comments

Quality Gates:

• Code follows project style guide
• All tests pass (unit, integration, e2e)
• No critical lint/security issues
• Documentation updated (README, code comments, ADRs)
• Meets all acceptance criteria
• Security audit for encryption implementation
• Performance benchmarks met

Review Checklist:

• Code review approved by @ArhonJay
• CI/CD pipeline passes
• Performance benchmarks met (if applicable)
• Security scan passes
• Encryption implementation reviewed

Delivery Status:

• Initial Status: To Do
• Progress Tracking: Use issue comments for updates
• Sign-off: Approved by @Hyperionkit on 2026-02-06
• PR Link: [Link to merged PR(s)]

Related Issues:

• Design workspace_providers table schema for LLM keys, Tenderly, RPC endpoints (encrypted, tenant-scoped) #273: Design workspace_providers table schema
• Implement Workspace Settings UI (Providers tab: LLM keys, Tenderly, RPC endpoints) #275: Implement Workspace Settings UI
• Implement TS SDK workspace provider methods (configureProvider, getProviders, updateProvider) #287: Implement TS SDK workspace provider methods

Documentation References:

• Platform Blueprint
• Scope Definition
• Execution Strategy
• Business Model
• Project Phases