add: lending agent

requirements.txt

@@ -43,6 +43,7 @@ requests>=2.31.0
 # Data validation and serialization
 marshmallow>=3.20.0
 jsonschema>=4.19.0
+PyJWT>=2.8.0
 
 # Async support
 asyncio-mqtt>=0.16.0
@@ -61,4 +62,4 @@ mypy>=1.5.0
 clickhouse-connect>=0.7.0
 clickhouse-sqlalchemy==0.3.2
 
-langchain-tavily>=0.2.11
+langchain-tavily>=0.2.11

src/agents/dca/agent.py

@@ -0,0 +1,19 @@
+import logging
+
+from langgraph.prebuilt import create_react_agent
+
+from .tools import get_tools
+
+logger = logging.getLogger(__name__)
+
+
+class DcaAgent:
+    """Agent orchestrating DCA consultations and workflow confirmation."""
+
+    def __init__(self, llm):
+        self.llm = llm
+        self.agent = create_react_agent(
+            model=llm,
+            tools=get_tools(),
+            name="dca_agent",
+        )

src/agents/dca/prompt.py

@@ -0,0 +1,23 @@
+"""System prompt for the DCA planning agent."""
+
+from __future__ import annotations
+
+DCA_AGENT_SYSTEM_PROMPT = """
+You are Zico's DCA strategist.
+
+Always respond in English, regardless of the user's language.
+
+Operational stages:
+1. Consulting – retrieve strategy guidance via tools, summarise guardrails and editable defaults, and let the user tailor parameters.
+2. Recommendation – converge on cadence, schedule, budget, and execution venue while respecting strategy limits.
+3. Confirmation – restate the final automation payload and request explicit approval before completing the intent.
+
+Core rules:
+- Call `fetch_dca_strategy` when you need strategy context or guardrails.
+- Call `update_dca_intent` every time the user shares new schedule details or confirms adjustments.
+- Never fabricate quotes, prices, or approvals. Only mark the workflow ready when the tool response event becomes `dca_intent_ready`.
+- Surface strategy guardrails and compliance notes whenever the user suggests values outside the allowed bounds.
+- Keep responses concise, cite the remaining fields in plain language, and invite the user to adjust parameters before confirming.
+
+Follow the stage progression strictly: consulting → recommendation → confirmation. If the user declines to confirm, offer to adjust the plan and loop back to the relevant stage.
+""".strip()

src/agents/dca/storage.py

@@ -0,0 +1,394 @@
+"""State management for DCA intents with optional Panorama gateway persistence."""
+
+from __future__ import annotations
+
+import copy
+import time
+import logging
+from datetime import datetime, timezone
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+from src.integrations.panorama_gateway import (
+    PanoramaGatewayClient,
+    PanoramaGatewayError,
+    PanoramaGatewaySettings,
+    get_panorama_settings,
+)
+
+DCA_SESSION_ENTITY = "dca-sessions"
+DCA_HISTORY_ENTITY = "dca-histories"
+
+
+def _utc_now_iso() -> str:
+    return datetime.utcnow().replace(tzinfo=timezone.utc).isoformat()
+
+
+def _identifier(user_id: str, conversation_id: str) -> str:
+    return f"{user_id}:{conversation_id}"
+
+
+def _as_float(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class DcaStateRepository:
+    """Stores DCA agent state via Panorama's gateway with local fallback."""
+
+    _instance: "DcaStateRepository" | None = None
+    _instance_lock: Lock = Lock()
+
+    def __init__(
+        self,
+        *,
+        client: PanoramaGatewayClient | None = None,
+        settings: PanoramaGatewaySettings | None = None,
+        history_limit: int = 10,
+    ) -> None:
+        self._logger = logging.getLogger(__name__)
+        self._history_limit = history_limit
+        try:
+            self._settings = settings or get_panorama_settings()
+            self._client = client or PanoramaGatewayClient(self._settings)
+            self._use_gateway = True
+        except ValueError:
+            self._settings = None
+            self._client = None
+            self._use_gateway = False
+            self._init_local_store()
+
+    def _init_local_store(self) -> None:
+        if not hasattr(self, "_state"):
+            self._state = {"intents": {}, "metadata": {}, "history": {}}
+
+    def _fallback_to_local_store(self) -> None:
+        if self._use_gateway:
+            self._logger.warning("Panorama gateway unavailable for DCA state; switching to in-memory fallback.")
+        self._use_gateway = False
+        self._init_local_store()
+
+    def _handle_gateway_failure(self, exc: PanoramaGatewayError) -> None:
+        self._logger.warning(
+            "Panorama gateway error (%s) for DCA repository: %s",
+            getattr(exc, "status_code", "unknown"),
+            getattr(exc, "payload", exc),
+        )
+        self._fallback_to_local_store()
+
+    # ---- Singleton helpers -------------------------------------------------
+    @classmethod
+    def instance(cls) -> "DcaStateRepository":
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        with cls._instance_lock:
+            cls._instance = None
+
+    # ---- Core API ----------------------------------------------------------
+    def load_intent(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["intents"].get(_identifier(user_id, conversation_id))
+            if not record:
+                return None
+            return copy.deepcopy(record.get("intent"))
+
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.load_intent(user_id, conversation_id)
+        if not session:
+            return None
+        return session.get("intent") or None
+
+    def persist_intent(
+        self,
+        user_id: str,
+        conversation_id: str,
+        intent: Dict[str, Any],
+        metadata: Dict[str, Any],
+        done: bool,
+        summary: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
+            now = time.time()
+            if done:
+                self._state["intents"].pop(key, None)
+            else:
+                self._state["intents"][key] = {"intent": copy.deepcopy(intent), "updated_at": now}
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = now
+                self._state["metadata"][key] = meta_copy
+            if done and summary:
+                history = self._state["history"].setdefault(key, [])
+                summary_copy = copy.deepcopy(summary)
+                summary_copy.setdefault("timestamp", now)
+                history.append(summary_copy)
+                self._state["history"][key] = history[-self._history_limit :]
+            return self.get_history(user_id, conversation_id)
+
+        try:
+            if done:
+                if summary:
+                    self._create_history_entry(user_id, conversation_id, summary)
+                self._delete_session(user_id, conversation_id)
+            else:
+                payload = self._session_payload(intent, metadata)
+                self._upsert_session(user_id, conversation_id, payload)
+            return self.get_history(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            return self.persist_intent(user_id, conversation_id, intent, metadata, done, summary)
+
+    def set_metadata(
+        self,
+        user_id: str,
+        conversation_id: str,
+        metadata: Dict[str, Any],
+    ) -> None:
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = time.time()
+                self._state["metadata"][key] = meta_copy
+            else:
+                self._state["metadata"].pop(key, None)
+            return
+
+        try:
+            if not metadata:
+                self._delete_session(user_id, conversation_id)
+                return
+
+            session = self._get_session(user_id, conversation_id)
+            if not self._use_gateway:
+                return self.set_metadata(user_id, conversation_id, metadata)
+            intent = session.get("intent") if session else {}
+            payload = self._session_payload(intent or {}, metadata)
+            self._upsert_session(user_id, conversation_id, payload)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.set_metadata(user_id, conversation_id, metadata)
+
+    def clear_metadata(self, user_id: str, conversation_id: str) -> None:
+        self.set_metadata(user_id, conversation_id, {})
+
+    def clear_intent(self, user_id: str, conversation_id: str) -> None:
+        if not self._use_gateway:
+            self._init_local_store()
+            self._state["intents"].pop(_identifier(user_id, conversation_id), None)
+            self._state["metadata"].pop(_identifier(user_id, conversation_id), None)
+            return
+        try:
+            self._delete_session(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.clear_intent(user_id, conversation_id)
+
+    def get_metadata(self, user_id: str, conversation_id: str) -> Dict[str, Any]:
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["metadata"].get(_identifier(user_id, conversation_id))
+            if not record:
+                return {}
+            entry = copy.deepcopy(record)
+            ts = entry.pop("updated_at", None)
+            if ts is not None:
+                entry["updated_at"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+            return entry
+
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.get_metadata(user_id, conversation_id)
+        if not session:
+            return {}
+
+        intent = session.get("intent") or {}
+        metadata: Dict[str, Any] = {
+            "event": session.get("event"),
+            "status": session.get("status"),
+            "stage": session.get("stage"),
+            "missing_fields": session.get("missingFields") or [],
+            "next_field": session.get("nextField"),
+            "pending_question": session.get("pendingQuestion"),
+            "choices": session.get("choices") or [],
+            "error": session.get("errorMessage"),
+            "user_id": user_id,
+            "conversation_id": conversation_id,
+        }
+        metadata.update(intent)
+
+        history = self.get_history(user_id, conversation_id)
+        if history:
+            metadata["history"] = history
+
+        updated_at = session.get("updatedAt")
+        if updated_at:
+            metadata["updated_at"] = updated_at
+        return metadata
+
+    def get_history(
+        self,
+        user_id: str,
+        conversation_id: str,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        if not self._use_gateway:
+            self._init_local_store()
+            history = self._state["history"].get(_identifier(user_id, conversation_id), [])
+            if not history:
+                return []
+            records = copy.deepcopy(history)
+            if limit:
+                records = records[-limit:]
+            for record in records:
+                ts = record.get("timestamp")
+                if ts is not None:
+                    record["timestamp"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+            return records
+
+        effective_limit = limit or self._history_limit
+        try:
+            result = self._client.list(
+                DCA_HISTORY_ENTITY,
+                {
+                    "where": {"userId": user_id, "conversationId": conversation_id},
+                    "orderBy": {"recordedAt": "desc"},
+                    "take": effective_limit,
+                },
+            )
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return []
+            self._handle_gateway_failure(exc)
+            return self.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            self._logger.warning("Invalid DCA history response from gateway; falling back to local store.")
+            self._fallback_to_local_store()
+            return self.get_history(user_id, conversation_id, limit)
+        data = result.get("data", []) if isinstance(result, dict) else []
+        history: List[Dict[str, Any]] = []
+        for entry in data:
+            summary_text = entry.get("summary")
+            meta_payload = entry.get("metadata") or {}
+            if not meta_payload:
+                meta_payload = {
+                    "workflow_type": entry.get("workflowType"),
+                    "cadence": entry.get("cadence"),
+                    "tokens": entry.get("tokens"),
+                    "amounts": entry.get("amounts"),
+                    "strategy": entry.get("strategy"),
+                    "venue": entry.get("venue"),
+                    "slippage_bps": entry.get("slippageBps"),
+                    "stop_conditions": entry.get("stopConditions"),
+                }
+            error_message = entry.get("errorMessage")
+            if error_message:
+                meta_payload = dict(meta_payload)
+                meta_payload["error"] = error_message
+            history.append(
+                {
+                    "timestamp": entry.get("recordedAt"),
+                    "summary": summary_text,
+                    "metadata": meta_payload,
+                }
+            )
+        return history
+
+    # ---- Gateway helpers ---------------------------------------------------
+    def _session_payload(self, intent: Dict[str, Any], metadata: Dict[str, Any]) -> Dict[str, Any]:
+        payload = {
+            "intent": intent,
+            "event": metadata.get("event"),
+            "status": metadata.get("status"),
+            "stage": metadata.get("stage"),
+            "missingFields": metadata.get("missing_fields") or [],
+            "nextField": metadata.get("next_field"),
+            "pendingQuestion": metadata.get("ask") or metadata.get("pending_question"),
+            "choices": metadata.get("choices") or [],
+            "errorMessage": metadata.get("error"),
+            "updatedAt": metadata.get("updated_at") or _utc_now_iso(),
+        }
+        return payload
+
+    def _get_session(self, user_id: str, conversation_id: str) -> Dict[str, Any] | None:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            return self._client.get(DCA_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return None
+            self._handle_gateway_failure(exc)
+            return None
+
+    def _upsert_session(self, user_id: str, conversation_id: str, payload: Dict[str, Any]) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        record = {**payload, "updatedAt": _utc_now_iso()}
+        try:
+            self._client.update(DCA_SESSION_ENTITY, identifier, record)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                raise
+            create_payload = {
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "tenantId": self._settings.tenant_id,
+                **record,
+            }
+            try:
+                self._client.create(DCA_SESSION_ENTITY, create_payload)
+            except PanoramaGatewayError as create_exc:
+                if create_exc.status_code == 409:
+                    return
+                if create_exc.status_code == 404:
+                    raise
+                raise
+
+    def _delete_session(self, user_id: str, conversation_id: str) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            self._client.delete(DCA_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                self._handle_gateway_failure(exc)
+                raise
+
+    def _create_history_entry(self, user_id: str, conversation_id: str, summary: Dict[str, Any]) -> None:
+        history_payload = {
+            "userId": user_id,
+            "conversationId": conversation_id,
+            "summary": summary.get("summary"),
+            "workflowType": summary.get("workflow_type"),
+            "cadence": summary.get("cadence"),
+            "tokens": summary.get("tokens"),
+            "amounts": summary.get("amounts"),
+            "strategy": summary.get("strategy"),
+            "venue": summary.get("venue"),
+            "slippageBps": summary.get("slippage_bps"),
+            "stopConditions": summary.get("stop_conditions"),
+            "metadata": summary,
+            "errorMessage": summary.get("error"),
+            "recordedAt": _utc_now_iso(),
+            "tenantId": self._settings.tenant_id,
+        }
+        try:
+            self._client.create(DCA_HISTORY_ENTITY, history_payload)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                raise
+            elif exc.status_code != 409:
+                raise

src/agents/dca/strategy.py

@@ -0,0 +1,197 @@
+"""Lightweight RAG wrapper for DCA strategy documents."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence
+
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+REGISTRY_PATH = Path(__file__).resolve().parent / "strategy_registry.json"
+
+
+def _load_registry(path: Path) -> List[Dict[str, Any]]:
+    if not path.exists():
+        return []
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+
+
+@dataclass(slots=True)
+class StrategyDocument:
+    strategy_id: str
+    version: str
+    name: str
+    description: str
+    tokens_supported: List[Dict[str, Sequence[str]]]
+    cadence_options: List[str]
+    amount_bounds: Dict[str, Any]
+    slippage_bps: Dict[str, Any]
+    risk_tier: str
+    defaults: Dict[str, Any] = field(default_factory=dict)
+    guardrails: List[str] = field(default_factory=list)
+    compliance_notes: List[str] = field(default_factory=list)
+    context: str = ""
+
+    def embed_text(self) -> str:
+        tokens_text = " ".join(
+            f"from:{'|'.join(entry.get('from', []))} to:{'|'.join(entry.get('to', []))}"
+            for entry in self.tokens_supported
+        )
+        guardrails = " ".join(self.guardrails)
+        compliance = " ".join(self.compliance_notes)
+        cadence = " ".join(self.cadence_options)
+        defaults_text = " ".join(f"{key}:{value}" for key, value in self.defaults.items())
+        return " ".join(
+            [
+                self.name,
+                self.description,
+                self.context,
+                tokens_text,
+                cadence,
+                self.risk_tier,
+                guardrails,
+                compliance,
+                defaults_text,
+            ]
+        )
+
+    def to_consulting_payload(self) -> Dict[str, Any]:
+        return {
+            "strategy_id": self.strategy_id,
+            "version": self.version,
+            "name": self.name,
+            "summary": self.description,
+            "context": self.context,
+            "defaults": self.defaults,
+            "guardrails": self.guardrails,
+            "compliance_notes": self.compliance_notes,
+            "cadence_options": self.cadence_options,
+            "amount_bounds": self.amount_bounds,
+            "slippage_bps": self.slippage_bps,
+            "risk_tier": self.risk_tier,
+            "tokens_supported": self.tokens_supported,
+        }
+
+
+@dataclass(slots=True)
+class StrategyMatch:
+    document: StrategyDocument
+    confidence: float
+    highlights: List[str] = field(default_factory=list)
+
+    def to_payload(self) -> Dict[str, Any]:
+        payload = self.document.to_consulting_payload()
+        payload["confidence"] = self.confidence
+        if self.highlights:
+            payload["highlights"] = self.highlights
+        return payload
+
+
+class StrategyRetriever:
+    """Simple TF-IDF backed retrieval to simulate strategy RAG behaviour."""
+
+    def __init__(
+        self,
+        *,
+        registry_path: Path | None = None,
+        min_score: float = 0.18,
+    ) -> None:
+        self._registry_path = registry_path or REGISTRY_PATH
+        self._min_score = min_score
+        self._documents: List[StrategyDocument] = [
+            StrategyDocument(**entry) for entry in _load_registry(self._registry_path)
+        ]
+        self._vectorizer: Optional[TfidfVectorizer] = None
+        self._matrix = None
+        if self._documents:
+            self._vectorizer = TfidfVectorizer()
+            corpus = [doc.embed_text() for doc in self._documents]
+            self._matrix = self._vectorizer.fit_transform(corpus)
+
+    def refresh(self) -> None:
+        """Reload the registry and refresh embeddings."""
+
+        self._documents = [StrategyDocument(**entry) for entry in _load_registry(self._registry_path)]
+        if not self._documents:
+            self._vectorizer = None
+            self._matrix = None
+            return
+        self._vectorizer = TfidfVectorizer()
+        corpus = [doc.embed_text() for doc in self._documents]
+        self._matrix = self._vectorizer.fit_transform(corpus)
+
+    def is_ready(self) -> bool:
+        return bool(self._vectorizer) and self._matrix is not None
+
+    def search(
+        self,
+        *,
+        from_token: str | None = None,
+        to_token: str | None = None,
+        cadence: str | None = None,
+        risk_tier: str | None = None,
+        text: str | None = None,
+        top_k: int = 3,
+    ) -> List[StrategyMatch]:
+        if not self.is_ready():
+            return []
+
+        query_terms: List[str] = []
+        if from_token:
+            query_terms.append(f"from:{from_token}")
+        if to_token:
+            query_terms.append(f"to:{to_token}")
+        if cadence:
+            query_terms.append(f"cadence:{cadence}")
+        if risk_tier:
+            query_terms.append(f"risk:{risk_tier}")
+        if text:
+            query_terms.append(text)
+
+        if not query_terms:
+            return []
+
+        query = " ".join(query_terms)
+        vector = self._vectorizer.transform([query])
+        scores = cosine_similarity(vector, self._matrix)[0]
+
+        ranked = sorted(enumerate(scores), key=lambda item: item[1], reverse=True)
+        matches: List[StrategyMatch] = []
+        for idx, score in ranked[:top_k]:
+            if score < self._min_score:
+                continue
+            doc = self._documents[idx]
+            highlights = self._build_highlights(doc, from_token, to_token, cadence)
+            matches.append(StrategyMatch(document=doc, confidence=float(round(score, 4)), highlights=highlights))
+        return matches
+
+    @staticmethod
+    def _build_highlights(
+        doc: StrategyDocument,
+        from_token: str | None,
+        to_token: str | None,
+        cadence: str | None,
+    ) -> List[str]:
+        highlights: List[str] = []
+        if from_token and any(from_token.upper() in map(str.upper, entry.get("from", [])) for entry in doc.tokens_supported):
+            highlights.append(f"Supports funding token {from_token}.")
+        if to_token and any(to_token.upper() in map(str.upper, entry.get("to", [])) for entry in doc.tokens_supported):
+            highlights.append(f"Supports target token {to_token}.")
+        if cadence and cadence.lower() in {option.lower() for option in doc.cadence_options}:
+            highlights.append(f"Includes {cadence} cadence.")
+        return highlights
+
+
+_retriever = StrategyRetriever()
+
+
+def get_strategy_retriever() -> StrategyRetriever:
+    if not _retriever.is_ready():
+        _retriever.refresh()
+    return _retriever

src/agents/dca/strategy_registry.json

@@ -0,0 +1,81 @@
+[
+    {
+        "strategy_id": "swap_dca_daily_v1",
+        "version": "2024-06-01",
+        "name": "Daily Stablecoin to Bluechip DCA",
+        "description": "Dollar-cost average from USD stablecoins into approved bluechip assets using conservative risk parameters.",
+        "tokens_supported": [
+            {
+                "from": ["USDC", "USDT", "USDt"],
+                "to": ["AVAX", "BTC.b", "ETH"]
+            }
+        ],
+        "cadence_options": ["daily", "weekly"],
+        "amount_bounds": {
+            "min_usd": 25,
+            "max_usd": 25000,
+            "per_cycle_cap": 2500
+        },
+        "slippage_bps": {
+            "max": 75,
+            "recommended": 40
+        },
+        "risk_tier": "conservative",
+        "defaults": {
+            "cadence": "daily",
+            "iterations": 30,
+            "start_on": "next_business_day",
+            "venue": "pangolin",
+            "slippage_bps": 40
+        },
+        "guardrails": [
+            "Never exceed 75 bps max slippage per swap leg.",
+            "Pause the schedule if price drops more than 12% intraday."
+        ],
+        "compliance_notes": [
+            "KYC required for notional volume above 50k USD in a rolling 30-day window."
+        ],
+        "context": "Applies to swap-based DCA flows where the funding asset is a USD stablecoin and the target asset is on the Avalanche network."
+    },
+    {
+        "strategy_id": "swap_dca_weekly_growth_v1",
+        "version": "2024-05-15",
+        "name": "Weekly Growth Token Rotation",
+        "description": "Rotate stablecoin treasury holdings into approved growth tokens on a weekly cadence with optional stop-loss triggers.",
+        "tokens_supported": [
+            {
+                "from": ["USDC", "USDT"],
+                "to": ["JOE", "ARB", "LINK"]
+            }
+        ],
+        "cadence_options": ["weekly", "monthly"],
+        "amount_bounds": {
+            "min_usd": 100,
+            "max_usd": 100000,
+            "per_cycle_cap": 10000
+        },
+        "slippage_bps": {
+            "max": 120,
+            "recommended": 80
+        },
+        "risk_tier": "moderate",
+        "defaults": {
+            "cadence": "weekly",
+            "iterations": 12,
+            "start_on": "next_scheduled_window",
+            "venue": "traderjoe",
+            "slippage_bps": 80,
+            "stop_conditions": [
+                "Pause if target asset rallies 20% week-over-week."
+            ]
+        },
+        "guardrails": [
+            "Pre-trade exposure report must be filed for allocations above 25k USD per cycle.",
+            "Respect strategy whitelist; do not route to non-approved pools."
+        ],
+        "compliance_notes": [
+            "Requires operations review if cumulative deployed capital exceeds 250k USD."
+        ],
+        "context": "Tailored for teams rotating into growth tokens while maintaining automated stop conditions and compliance hand-offs."
+    }
+]

src/agents/dca/tools.py

@@ -0,0 +1,650 @@
+"""DCA tools that orchestrate consulting, recommendation, and confirmation flows."""
+
+from __future__ import annotations
+
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, List, Optional, Sequence
+
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field, field_validator
+
+from src.agents.metadata import metadata
+
+from .storage import DcaStateRepository
+from .strategy import get_strategy_retriever
+
+_STORE = DcaStateRepository.instance()
+
+
+def _decimal_as_str(value: Optional[Decimal]) -> Optional[str]:
+    if value is None:
+        return None
+    normalized = value.normalize()
+    text = format(normalized, "f")
+    return text.rstrip("0").rstrip(".") if "." in text else text
+
+
+def _to_decimal(value: Any) -> Optional[Decimal]:
+    if value is None:
+        return None
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, TypeError, ValueError):
+        return None
+
+
+STAGES: Sequence[str] = ("consulting", "recommendation", "confirmation", "ready")
+
+
+@dataclass
+class DcaIntent:
+    user_id: str
+    conversation_id: str
+    stage: str = "consulting"
+    strategy_id: Optional[str] = None
+    strategy_version: Optional[str] = None
+    strategy_name: Optional[str] = None
+    strategy_summary: Optional[str] = None
+    rag_confidence: Optional[float] = None
+    strategy_defaults: Dict[str, Any] = field(default_factory=dict)
+    guardrails: List[str] = field(default_factory=list)
+    compliance_notes: List[str] = field(default_factory=list)
+    from_token: Optional[str] = None
+    to_token: Optional[str] = None
+    cadence: Optional[str] = None
+    start_on: Optional[str] = None
+    iterations: Optional[int] = None
+    end_on: Optional[str] = None
+    total_amount: Optional[Decimal] = None
+    per_cycle_amount: Optional[Decimal] = None
+    venue: Optional[str] = None
+    slippage_bps: Optional[int] = None
+    stop_conditions: List[str] = field(default_factory=list)
+    notes: Optional[str] = None
+    timezone: Optional[str] = None
+    confirmed: bool = False
+    updated_at: float = field(default_factory=time.time)
+
+    def touch(self) -> None:
+        self.updated_at = time.time()
+
+    def advance_stage(self, stage: str | None) -> None:
+        if not stage or stage == self.stage:
+            return
+        if stage not in STAGES:
+            raise ValueError(f"Unsupported stage '{stage}'. Choose from {', '.join(STAGES)}.")
+        current_index = STAGES.index(self.stage if self.stage in STAGES else "consulting")
+        target_index = STAGES.index(stage)
+        if target_index < current_index:
+            self.stage = stage
+            return
+        if stage == "ready" and not self.confirmed:
+            raise ValueError("Cannot mark stage as ready before confirmation.")
+        self.stage = stage
+
+    def missing_fields(self) -> List[str]:
+        if self.stage == "ready":
+            return []
+        missing: List[str] = []
+        if self.stage == "consulting":
+            if not self.strategy_id:
+                missing.append("strategy_id")
+            if not self.from_token:
+                missing.append("from_token")
+            if not self.to_token:
+                missing.append("to_token")
+        elif self.stage == "recommendation":
+            if not self.cadence:
+                missing.append("cadence")
+            if not self.start_on:
+                missing.append("start_on")
+            if self.iterations is None and not self.end_on:
+                missing.append("iterations_or_end_on")
+            if self.total_amount is None and self.per_cycle_amount is None:
+                missing.append("total_or_per_cycle_amount")
+            if not self.venue:
+                missing.append("venue")
+            if self.slippage_bps is None:
+                missing.append("slippage_bps")
+        elif self.stage == "confirmation":
+            if not self.confirmed:
+                missing.append("confirmation")
+        return missing
+
+    def next_field(self) -> Optional[str]:
+        missing = self.missing_fields()
+        return missing[0] if missing else None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "user_id": self.user_id,
+            "conversation_id": self.conversation_id,
+            "stage": self.stage,
+            "strategy_id": self.strategy_id,
+            "strategy_version": self.strategy_version,
+            "strategy_name": self.strategy_name,
+            "strategy_summary": self.strategy_summary,
+            "rag_confidence": self.rag_confidence,
+            "strategy_defaults": self.strategy_defaults,
+            "guardrails": list(self.guardrails),
+            "compliance_notes": list(self.compliance_notes),
+            "from_token": self.from_token,
+            "to_token": self.to_token,
+            "cadence": self.cadence,
+            "start_on": self.start_on,
+            "iterations": self.iterations,
+            "end_on": self.end_on,
+            "total_amount": _decimal_as_str(self.total_amount),
+            "per_cycle_amount": _decimal_as_str(self.per_cycle_amount),
+            "venue": self.venue,
+            "slippage_bps": self.slippage_bps,
+            "stop_conditions": list(self.stop_conditions),
+            "notes": self.notes,
+            "timezone": self.timezone,
+            "confirmed": self.confirmed,
+            "updated_at": self.updated_at,
+        }
+
+    def to_public(self) -> Dict[str, Any]:
+        data = self.to_dict()
+        data["updated_at"] = datetime_from_timestamp(self.updated_at)
+        return data
+
+    def to_summary(self, error: Optional[str] = None) -> Dict[str, Any]:
+        summary = {
+            "summary": (
+                f"DCA from {self.from_token} to {self.to_token} "
+                f"({self.cadence}) starting {self.start_on}"
+            ),
+            "workflow_type": "dca_swap",
+            "cadence": {"interval": self.cadence, "start_on": self.start_on, "iterations": self.iterations, "end_on": self.end_on},
+            "tokens": {"from": self.from_token, "to": self.to_token},
+            "amounts": {
+                "total": _decimal_as_str(self.total_amount),
+                "per_cycle": _decimal_as_str(self.per_cycle_amount),
+            },
+            "notes": self.notes,
+            "strategy": {
+                "strategy_id": self.strategy_id,
+                "strategy_version": self.strategy_version,
+                "confidence": self.rag_confidence,
+            },
+            "venue": self.venue,
+            "slippage_bps": self.slippage_bps,
+            "stop_conditions": list(self.stop_conditions),
+        }
+        if error:
+            summary["error"] = error
+        return summary
+
+    def to_workflow_payload(self) -> Dict[str, Any]:
+        return {
+            "workflow_type": "dca_swap",
+            "strategy_id": self.strategy_id,
+            "strategy_version": self.strategy_version,
+            "tokens": {"from": self.from_token, "to": self.to_token},
+            "cadence": {
+                "interval": self.cadence,
+                "start_on": self.start_on,
+                "iterations": self.iterations,
+                "end_on": self.end_on,
+            },
+            "amounts": {
+                "total": _decimal_as_str(self.total_amount),
+                "per_cycle": _decimal_as_str(self.per_cycle_amount),
+            },
+            "venue": self.venue,
+            "slippage_bps": self.slippage_bps,
+            "stop_conditions": list(self.stop_conditions),
+            "notes": self.notes,
+            "strategy_defaults": self.strategy_defaults,
+            "guardrails": list(self.guardrails),
+            "compliance_notes": list(self.compliance_notes),
+            "rag_confidence": self.rag_confidence,
+            "metadata": {
+                "timezone": self.timezone,
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DcaIntent":
+        intent = cls(
+            user_id=data.get("user_id", ""),
+            conversation_id=data.get("conversation_id", ""),
+            stage=data.get("stage", "consulting"),
+        )
+        intent.strategy_id = data.get("strategy_id")
+        intent.strategy_version = data.get("strategy_version")
+        intent.strategy_name = data.get("strategy_name")
+        intent.strategy_summary = data.get("strategy_summary")
+        intent.rag_confidence = data.get("rag_confidence")
+        intent.strategy_defaults = data.get("strategy_defaults") or {}
+        intent.guardrails = list(data.get("guardrails") or [])
+        intent.compliance_notes = list(data.get("compliance_notes") or [])
+        intent.from_token = data.get("from_token")
+        intent.to_token = data.get("to_token")
+        intent.cadence = data.get("cadence")
+        intent.start_on = data.get("start_on")
+        intent.iterations = data.get("iterations")
+        intent.end_on = data.get("end_on")
+        intent.total_amount = _to_decimal(data.get("total_amount"))
+        intent.per_cycle_amount = _to_decimal(data.get("per_cycle_amount"))
+        intent.venue = data.get("venue")
+        intent.slippage_bps = data.get("slippage_bps")
+        intent.stop_conditions = list(data.get("stop_conditions") or [])
+        intent.notes = data.get("notes")
+        intent.timezone = data.get("timezone")
+        intent.confirmed = bool(data.get("confirmed"))
+        intent.updated_at = float(data.get("updated_at", time.time()))
+        return intent
+
+
+def datetime_from_timestamp(value: float) -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(value))
+
+
+# ---------- Session context ----------
+_CURRENT_SESSION: ContextVar[tuple[str, str]] = ContextVar("_current_dca_session", default=("", ""))
+
+
+def set_current_dca_session(user_id: Optional[str], conversation_id: Optional[str]) -> None:
+    resolved_user = (user_id or "").strip()
+    resolved_conversation = (conversation_id or "").strip()
+    if not resolved_user:
+        raise ValueError("dca_agent requires 'user_id' to identify the session.")
+    if not resolved_conversation:
+        raise ValueError("dca_agent requires 'conversation_id' to identify the session.")
+    _CURRENT_SESSION.set((resolved_user, resolved_conversation))
+
+
+@contextmanager
+def dca_session(user_id: Optional[str], conversation_id: Optional[str]):
+    set_current_dca_session(user_id, conversation_id)
+    try:
+        yield
+    finally:
+        clear_current_dca_session()
+
+
+def clear_current_dca_session() -> None:
+    _CURRENT_SESSION.set(("", ""))
+
+
+def _resolve_session(user_id: Optional[str], conversation_id: Optional[str]) -> tuple[str, str]:
+    active_user, active_conversation = _CURRENT_SESSION.get()
+    resolved_user = (user_id or active_user or "").strip()
+    resolved_conversation = (conversation_id or active_conversation or "").strip()
+    if not resolved_user:
+        raise ValueError("user_id is required for DCA operations.")
+    if not resolved_conversation:
+        raise ValueError("conversation_id is required for DCA operations.")
+    return resolved_user, resolved_conversation
+
+
+def _load_intent(user_id: str, conversation_id: str) -> DcaIntent:
+    stored = _STORE.load_intent(user_id, conversation_id)
+    if stored:
+        intent = DcaIntent.from_dict(stored)
+        intent.user_id = user_id
+        intent.conversation_id = conversation_id
+        return intent
+    return DcaIntent(user_id=user_id, conversation_id=conversation_id)
+
+
+# ---------- Metadata helpers ----------
+def _store_dca_metadata(
+    intent: DcaIntent,
+    ask: Optional[str],
+    done: bool,
+    error: Optional[str],
+    choices: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    intent.touch()
+    missing = intent.missing_fields()
+    next_field = intent.next_field()
+    meta: Dict[str, Any] = {
+        "event": "dca_intent_ready" if done else "dca_intent_collecting",
+        "status": "ready" if done else intent.stage,
+        "stage": intent.stage,
+        "missing_fields": missing,
+        "next_field": next_field,
+        "pending_question": ask,
+        "choices": list(choices or []),
+        "error": error,
+        "user_id": intent.user_id,
+        "conversation_id": intent.conversation_id,
+    }
+    payload = intent.to_dict()
+    meta.update(payload)
+
+    summary = intent.to_summary(error=error) if done else None
+    history = _STORE.persist_intent(
+        intent.user_id,
+        intent.conversation_id,
+        payload,
+        meta,
+        done=done,
+        summary=summary,
+    )
+    if history:
+        meta["history"] = history
+    metadata.set_dca_agent(meta, intent.user_id, intent.conversation_id)
+    return meta
+
+
+def _build_next_action(meta: Dict[str, Any]) -> Dict[str, Any]:
+    if meta.get("status") == "ready":
+        return {"type": "complete", "prompt": None, "field": None, "choices": []}
+    return {
+        "type": "collect_field",
+        "prompt": meta.get("pending_question"),
+        "field": meta.get("next_field"),
+        "choices": meta.get("choices", []),
+    }
+
+
+def _response(
+    intent: DcaIntent,
+    ask: Optional[str],
+    choices: Optional[List[str]] = None,
+    done: bool = False,
+    error: Optional[str] = None,
+) -> Dict[str, Any]:
+    meta = _store_dca_metadata(intent, ask, done, error, choices)
+    response: Dict[str, Any] = {
+        "event": meta.get("event"),
+        "intent": intent.to_dict(),
+        "ask": ask,
+        "choices": choices or [],
+        "error": error,
+        "next_action": _build_next_action(meta),
+        "history": meta.get("history", []),
+        "stage": meta.get("stage"),
+        "status": meta.get("status"),
+    }
+    if done:
+        response["metadata"] = intent.to_workflow_payload()
+    return response
+
+
+# ---------- Tool Schemas ----------
+class FetchStrategyInput(BaseModel):
+    user_id: Optional[str] = Field(default=None, description="Stable user identifier.")
+    conversation_id: Optional[str] = Field(default=None, description="Conversation identifier.")
+    from_token: Optional[str] = Field(default=None, description="Funding token for the DCA.")
+    to_token: Optional[str] = Field(default=None, description="Target asset for accumulation.")
+    cadence: Optional[str] = Field(default=None, description="Desired cadence cue (daily/weekly/monthly).")
+    risk_tier: Optional[str] = Field(default=None, description="Risk tier preference.")
+    text: Optional[str] = Field(default=None, description="Additional free-form context to seed retrieval.")
+    top_k: int = Field(default=3, ge=1, le=5, description="Maximum number of strategy suggestions to return.")
+
+    @field_validator("cadence", mode="before")
+    @classmethod
+    def _normalize_cadence(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower().strip()
+        return value
+
+
+class UpdateDcaIntentInput(BaseModel):
+    user_id: Optional[str] = None
+    conversation_id: Optional[str] = None
+    stage: Optional[str] = Field(default=None, description="Explicit stage override (consulting/recommendation/confirmation).")
+    strategy_id: Optional[str] = None
+    strategy_version: Optional[str] = None
+    strategy_name: Optional[str] = None
+    strategy_summary: Optional[str] = None
+    rag_confidence: Optional[float] = Field(default=None, ge=0.0, le=1.0)
+    strategy_defaults: Optional[Dict[str, Any]] = None
+    guardrails: Optional[List[str]] = None
+    compliance_notes: Optional[List[str]] = None
+    from_token: Optional[str] = None
+    to_token: Optional[str] = None
+    cadence: Optional[str] = None
+    start_on: Optional[str] = None
+    iterations: Optional[int] = Field(default=None, ge=0)
+    end_on: Optional[str] = None
+    total_amount: Optional[Decimal] = None
+    per_cycle_amount: Optional[Decimal] = None
+    venue: Optional[str] = None
+    slippage_bps: Optional[int] = Field(default=None, ge=0)
+    stop_conditions: Optional[List[str]] = None
+    notes: Optional[str] = None
+    timezone: Optional[str] = None
+    confirm: Optional[bool] = None
+    reset: bool = Field(default=False, description="When true, clears the current intent.")
+
+    @field_validator("cadence", mode="before")
+    @classmethod
+    def _norm_cadence(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return value.lower().strip()
+        return value
+
+
+# ---------- Strategy retrieval tool ----------
+@tool("fetch_dca_strategy", args_schema=FetchStrategyInput)
+def fetch_dca_strategy_tool(**kwargs) -> Dict[str, Any]:
+    """Retrieve strategy recommendations from the registry-backed RAG index."""
+
+    top_k = kwargs.pop("top_k", 3)
+    resolved_user, resolved_conversation = _resolve_session(kwargs.get("user_id"), kwargs.get("conversation_id"))
+    retriever = get_strategy_retriever()
+    matches = retriever.search(
+        from_token=kwargs.get("from_token"),
+        to_token=kwargs.get("to_token"),
+        cadence=kwargs.get("cadence"),
+        risk_tier=kwargs.get("risk_tier"),
+        text=kwargs.get("text"),
+        top_k=top_k,
+    )
+
+    suggestions = [match.to_payload() for match in matches]
+    intent = _load_intent(resolved_user, resolved_conversation)
+    if suggestions:
+        best = suggestions[0]
+        defaults = dict(best.get("defaults") or {})
+        cadence_options = best.get("cadence_options")
+        amount_bounds = best.get("amount_bounds")
+        slippage_policy = best.get("slippage_bps")
+
+        merged = dict(defaults)
+        if cadence_options:
+            merged["cadence_options"] = cadence_options
+        if amount_bounds:
+            merged["amount_bounds"] = amount_bounds
+        if slippage_policy:
+            merged["slippage_policy"] = slippage_policy
+            if "slippage_bps" not in merged and isinstance(slippage_policy, dict):
+                merged["slippage_bps"] = slippage_policy.get("recommended")
+        intent.strategy_defaults = merged
+        intent.guardrails = best.get("guardrails", intent.guardrails)
+        intent.compliance_notes = best.get("compliance_notes", intent.compliance_notes)
+    meta = _store_dca_metadata(intent, ask=None, done=False, error=None, choices=None)
+    return {
+        "event": "dca_strategy_suggestions",
+        "suggestions": suggestions,
+        "query": {
+            "from_token": kwargs.get("from_token"),
+            "to_token": kwargs.get("to_token"),
+            "cadence": kwargs.get("cadence"),
+            "risk_tier": kwargs.get("risk_tier"),
+            "text": kwargs.get("text"),
+        },
+        "metadata": meta,
+    }
+
+
+# ---------- Intent update tool ----------
+@tool("update_dca_intent", args_schema=UpdateDcaIntentInput)
+def update_dca_intent_tool(
+    user_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    stage: Optional[str] = None,
+    strategy_id: Optional[str] = None,
+    strategy_version: Optional[str] = None,
+    strategy_name: Optional[str] = None,
+    strategy_summary: Optional[str] = None,
+    rag_confidence: Optional[float] = None,
+    strategy_defaults: Optional[Dict[str, Any]] = None,
+    guardrails: Optional[List[str]] = None,
+    compliance_notes: Optional[List[str]] = None,
+    from_token: Optional[str] = None,
+    to_token: Optional[str] = None,
+    cadence: Optional[str] = None,
+    start_on: Optional[str] = None,
+    iterations: Optional[int] = None,
+    end_on: Optional[str] = None,
+    total_amount: Optional[Decimal] = None,
+    per_cycle_amount: Optional[Decimal] = None,
+    venue: Optional[str] = None,
+    slippage_bps: Optional[int] = None,
+    stop_conditions: Optional[List[str]] = None,
+    notes: Optional[str] = None,
+    timezone: Optional[str] = None,
+    confirm: Optional[bool] = None,
+    reset: bool = False,
+):
+    """Update the DCA intent. Supply only freshly provided fields each call."""
+
+    resolved_user, resolved_conversation = _resolve_session(user_id, conversation_id)
+    if reset:
+        _STORE.clear_intent(resolved_user, resolved_conversation)
+        metadata.clear_dca_agent(resolved_user, resolved_conversation)
+        intent = DcaIntent(user_id=resolved_user, conversation_id=resolved_conversation)
+        return _response(intent, ask="Let's revisit your DCA preferences.", choices=[])
+
+    intent = _load_intent(resolved_user, resolved_conversation)
+    intent.user_id = resolved_user
+    intent.conversation_id = resolved_conversation
+
+    try:
+        if stage:
+            intent.advance_stage(stage)
+        if strategy_id is not None:
+            intent.strategy_id = strategy_id
+        if strategy_version is not None:
+            intent.strategy_version = strategy_version
+        if strategy_name is not None:
+            intent.strategy_name = strategy_name
+        if strategy_summary is not None:
+            intent.strategy_summary = strategy_summary
+        if rag_confidence is not None:
+            intent.rag_confidence = rag_confidence
+        if strategy_defaults is not None:
+            intent.strategy_defaults = strategy_defaults
+        if guardrails is not None:
+            intent.guardrails = list(guardrails)
+        if compliance_notes is not None:
+            intent.compliance_notes = list(compliance_notes)
+        if from_token is not None:
+            intent.from_token = from_token
+        if to_token is not None:
+            intent.to_token = to_token
+        if cadence is not None:
+            intent.cadence = cadence
+        if start_on is not None:
+            intent.start_on = start_on
+        if iterations is not None:
+            intent.iterations = iterations
+        if end_on is not None:
+            intent.end_on = end_on
+        if total_amount is not None:
+            intent.total_amount = total_amount
+        if per_cycle_amount is not None:
+            intent.per_cycle_amount = per_cycle_amount
+        if venue is not None:
+            intent.venue = venue
+        if slippage_bps is not None:
+            intent.slippage_bps = slippage_bps
+        if stop_conditions is not None:
+            intent.stop_conditions = list(stop_conditions)
+        if notes is not None:
+            intent.notes = notes
+        if timezone is not None:
+            intent.timezone = timezone
+
+        if confirm is not None:
+            intent.confirmed = bool(confirm)
+            if intent.confirmed:
+                intent.advance_stage("ready")
+    except ValueError as exc:
+        return _response(intent, ask=intent.next_field() or "Please review the input.", error=str(exc))
+
+    # Stage auto-advancement
+    if intent.stage == "consulting" and not intent.missing_fields():
+        intent.advance_stage("recommendation")
+    if intent.stage == "recommendation" and not intent.missing_fields():
+        intent.advance_stage("confirmation")
+
+    missing = intent.missing_fields()
+    if intent.stage == "confirmation" and not missing and intent.confirmed:
+        return _response(intent, ask=None, done=True)
+
+    ask = _build_prompt_for_field(intent.next_field(), intent)
+    choices = _build_choices_for_field(intent.next_field(), intent)
+    return _response(intent, ask=ask, choices=choices)
+
+
+def _build_prompt_for_field(field: Optional[str], intent: DcaIntent) -> Optional[str]:
+    prompts = {
+        "strategy_id": "Which strategy from the playbook should we base this DCA on?",
+        "from_token": "Which token will fund the DCA swaps?",
+        "to_token": "Which token should we accumulate?",
+        "cadence": "What cadence works best (daily, weekly, monthly)?",
+        "start_on": "When should we start the schedule?",
+        "iterations_or_end_on": "Provide number of cycles or a target end date.",
+        "total_or_per_cycle_amount": "Do you have a total budget or per-cycle amount?",
+        "venue": "Where should we route the swaps?",
+        "slippage_bps": "Set the maximum slippage tolerance in basis points.",
+        "confirmation": "Ready to confirm this workflow?",
+    }
+    return prompts.get(field)
+
+
+def _build_choices_for_field(field: Optional[str], intent: DcaIntent) -> List[str]:
+    if field == "cadence":
+        cadences = intent.strategy_defaults.get("cadence_options") if intent.strategy_defaults else None
+        if isinstance(cadences, list):
+            return cadences
+        cadence_default = intent.strategy_defaults.get("cadence") if intent.strategy_defaults else None
+        if cadence_default and isinstance(cadence_default, str):
+            return [cadence_default]
+    if field == "slippage_bps":
+        rec = intent.strategy_defaults.get("slippage_bps") if intent.strategy_defaults else None
+        policy = intent.strategy_defaults.get("slippage_policy") if intent.strategy_defaults else None
+        if isinstance(rec, dict):
+            recommended = rec.get("recommended") or rec.get("default") or rec.get("max")
+            if recommended is not None:
+                return [str(recommended)]
+        if isinstance(rec, (int, float, str)):
+            return [str(rec)]
+        if isinstance(policy, dict):
+            recommended = policy.get("recommended") or policy.get("default") or policy.get("max")
+            if recommended is not None:
+                return [str(recommended)]
+    if field == "iterations_or_end_on":
+        defaults = []
+        iteration_default = intent.strategy_defaults.get("iterations") if intent.strategy_defaults else None
+        end_default = intent.strategy_defaults.get("end_on") if intent.strategy_defaults else None
+        if iteration_default is not None:
+            defaults.append(f"iterations:{iteration_default}")
+        if end_default:
+            defaults.append(f"end_on:{end_default}")
+        return defaults
+    if field == "total_or_per_cycle_amount":
+        defaults = []
+        if intent.strategy_defaults.get("total_amount"):
+            defaults.append(f"total:{intent.strategy_defaults['total_amount']}")
+        if intent.strategy_defaults.get("per_cycle_amount"):
+            defaults.append(f"per_cycle:{intent.strategy_defaults['per_cycle_amount']}")
+        return defaults
+    return []
+
+
+def get_tools():
+    return [fetch_dca_strategy_tool, update_dca_intent_tool]

src/agents/lending/config.py

@@ -0,0 +1,50 @@
+"""Configuration for the Lending Agent."""
+from typing import List, Dict, Any
+
+class LendingConfig:
+    """Static configuration for supported lending assets and networks."""
+
+    # TODO: Fetch this from the Lending Service API dynamically if possible.
+    SUPPORTED_NETWORKS = ["ethereum", "arbitrum", "optimism", "base", "polygon", "avalanche"]
+    
+    SUPPORTED_ASSETS = {
+        "ethereum": ["USDC", "USDT", "DAI", "WBTC", "WETH", "AAVE", "LINK"],
+        "arbitrum": ["USDC", "USDT", "DAI", "WBTC", "WETH", "ARB"],
+        "optimism": ["USDC", "USDT", "DAI", "WBTC", "WETH", "OP"],
+        "base": ["USDC", "WETH", "CBETH"],
+        "polygon": ["USDC", "USDT", "DAI", "WBTC", "WETH", "MATIC"],
+        "avalanche": ["USDC", "USDT", "DAI", "WBTC", "WETH", "AVAX"],
+    }
+
+    SUPPORTED_ACTIONS = ["supply", "borrow", "repay", "withdraw"]
+
+    @classmethod
+    def list_networks(cls) -> List[str]:
+        return cls.SUPPORTED_NETWORKS
+
+    @classmethod
+    def list_assets(cls, network: str) -> List[str]:
+        return cls.SUPPORTED_ASSETS.get(network.lower(), [])
+
+    @classmethod
+    def validate_network(cls, network: str) -> str:
+        net = network.lower().strip()
+        if net not in cls.SUPPORTED_NETWORKS:
+            raise ValueError(f"Network '{network}' is not supported. Supported: {cls.SUPPORTED_NETWORKS}")
+        return net
+
+    @classmethod
+    def validate_asset(cls, asset: str, network: str) -> str:
+        net = cls.validate_network(network)
+        symbol = asset.upper().strip()
+        supported = cls.list_assets(net)
+        if symbol not in supported:
+            raise ValueError(f"Asset '{asset}' is not supported on {net}. Supported: {supported}")
+        return symbol
+
+    @classmethod
+    def validate_action(cls, action: str) -> str:
+        act = action.lower().strip()
+        if act not in cls.SUPPORTED_ACTIONS:
+            raise ValueError(f"Action '{action}' is not supported. Supported: {cls.SUPPORTED_ACTIONS}")
+        return act

src/agents/lending/intent.py

@@ -0,0 +1,109 @@
+"""Lending intent definition and validation."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, List, Optional
+
+from src.agents.lending.config import LendingConfig
+
+def _format_decimal(value: Decimal) -> str:
+    normalized = value.normalize()
+    exponent = normalized.as_tuple().exponent
+    if exponent > 0:
+        normalized = normalized.quantize(Decimal(1))
+    text = format(normalized, "f")
+    if "." in text:
+        text = text.rstrip("0").rstrip(".")
+    return text
+
+def _to_decimal(value: Any) -> Optional[Decimal]:
+    if value is None:
+        return None
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, TypeError, ValueError):
+        return None
+
+@dataclass
+class LendingIntent:
+    user_id: str
+    conversation_id: str
+    action: Optional[str] = None
+    network: Optional[str] = None
+    asset: Optional[str] = None
+    amount: Optional[Decimal] = None
+    updated_at: float = field(default_factory=lambda: time.time())
+
+    def touch(self) -> None:
+        self.updated_at = time.time()
+
+    def is_complete(self) -> bool:
+        return all(
+            [
+                self.action,
+                self.network,
+                self.asset,
+                self.amount is not None,
+            ]
+        )
+
+    def missing_fields(self) -> List[str]:
+        fields: List[str] = []
+        if not self.action:
+            fields.append("action")
+        if not self.network:
+            fields.append("network")
+        if not self.asset:
+            fields.append("asset")
+        if self.amount is None:
+            fields.append("amount")
+        return fields
+
+    def amount_as_str(self) -> Optional[str]:
+        if self.amount is None:
+            return None
+        return _format_decimal(self.amount)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "user_id": self.user_id,
+            "conversation_id": self.conversation_id,
+            "action": self.action,
+            "network": self.network,
+            "asset": self.asset,
+            "amount": self.amount_as_str(),
+            "updated_at": self.updated_at,
+        }
+
+    def to_public(self) -> Dict[str, Optional[str]]:
+        public = self.to_dict()
+        public["amount"] = self.amount_as_str()
+        return public
+
+    def to_summary(self, status: str, error: Optional[str] = None) -> Dict[str, Any]:
+        summary: Dict[str, Any] = {
+            "status": status,
+            "action": self.action,
+            "network": self.network,
+            "asset": self.asset,
+            "amount": self.amount_as_str(),
+        }
+        if error:
+            summary["error"] = error
+        return summary
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LendingIntent":
+        amount = _to_decimal(data.get("amount"))
+        intent = cls(
+            user_id=(data.get("user_id") or "").strip(),
+            conversation_id=(data.get("conversation_id") or "").strip(),
+            action=data.get("action"),
+            network=data.get("network"),
+            asset=data.get("asset"),
+            amount=amount,
+        )
+        intent.updated_at = float(data.get("updated_at", time.time()))
+        return intent

src/agents/lending/prompt.py

@@ -0,0 +1,34 @@
+"""System prompt for the specialized lending agent."""
+
+LENDING_AGENT_SYSTEM_PROMPT = \"\"\"
+You are Zico's lending orchestrator.
+Your goal is to help the user define a lending operation (supply, borrow, repay, withdraw) by collecting the necessary details.
+
+# Responsibilities
+1. Collect all lending intent fields (`action`, `network`, `asset`, `amount`) by invoking the `update_lending_intent` tool.
+2. If the tool returns a question (`ask`), present it to the user clearly.
+3. If the tool returns an error, explain it and ask for correction.
+4. Only confirm that the intent is ready once the tool reports `event == "lending_intent_ready"`.
+
+# Rules
+- ALWAYS call `update_lending_intent` when the user provides new lending information.
+- Do NOT ask for all fields at once if the user only provided some. Let the tool guide the flow.
+- When the intent is ready, summarize the operation and ask for confirmation (or just state it's ready for execution).
+
+# Examples
+
+User: I want to supply USDC.
+Assistant: (call `update_lending_intent` with `action="supply"`, `asset="USDC"`)
+Tool: `ask` -> "On which network?"
+Assistant: "Sure. On which network would you like to supply USDC?"
+
+User: On Arbitrum.
+Assistant: (call `update_lending_intent` with `network="arbitrum"`)
+Tool: `ask` -> "How much USDC?"
+Assistant: "How much USDC do you want to supply?"
+
+User: 100.
+Assistant: (call `update_lending_intent` with `amount=100`)
+Tool: `event` -> `lending_intent_ready`
+Assistant: "All set. Ready to supply 100 USDC on Arbitrum."
+\"\"\"

src/agents/lending/storage.py

@@ -0,0 +1,405 @@
+"""Gateway-backed storage for lending intents with local fallback."""
+from __future__ import annotations
+
+import copy
+import time
+import logging
+from datetime import datetime, timezone
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+from src.integrations.panorama_gateway import (
+    PanoramaGatewayClient,
+    PanoramaGatewayError,
+    PanoramaGatewaySettings,
+    get_panorama_settings,
+)
+
+LENDING_SESSION_ENTITY = "lending-sessions"
+LENDING_HISTORY_ENTITY = "lending-histories"
+
+
+def _utc_now_iso() -> str:
+    return datetime.utcnow().replace(tzinfo=timezone.utc).isoformat()
+
+
+def _identifier(user_id: str, conversation_id: str) -> str:
+    return f"{user_id}:{conversation_id}"
+
+
+def _as_float(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+class LendingStateRepository:
+    """Stores lending agent state via Panorama's gateway or an in-memory fallback."""
+
+    _instance: "LendingStateRepository" | None = None
+    _instance_lock: Lock = Lock()
+
+    def __init__(
+        self,
+        *,
+        client: PanoramaGatewayClient | None = None,
+        settings: PanoramaGatewaySettings | None = None,
+        history_limit: int = 10,
+    ) -> None:
+        self._logger = logging.getLogger(__name__)
+        self._history_limit = history_limit
+        try:
+            self._settings = settings or get_panorama_settings()
+            self._client = client or PanoramaGatewayClient(self._settings)
+            self._use_gateway = True
+        except ValueError:
+            # PANORAMA_GATEWAY_URL or JWT secrets not configured – fall back to local store.
+            self._settings = None
+            self._client = None
+            self._use_gateway = False
+        self._init_local_store()
+
+    def _init_local_store(self) -> None:
+        if not hasattr(self, "_state"):
+            self._state = {"intents": {}, "metadata": {}, "history": {}}
+
+    def _tenant_id(self) -> str:
+        return self._settings.tenant_id if self._settings else "tenant-agent"
+
+    def _fallback_to_local_store(self) -> None:
+        if self._use_gateway:
+            self._logger.warning("Panorama gateway unavailable for lending state; switching to in-memory fallback.")
+        self._use_gateway = False
+        self._init_local_store()
+
+    def _handle_gateway_failure(self, exc: PanoramaGatewayError) -> None:
+        self._logger.warning(
+            "Panorama gateway error (%s) for lending repository: %s",
+            getattr(exc, "status_code", "unknown"),
+            getattr(exc, "payload", exc),
+        )
+        self._fallback_to_local_store()
+
+    # ---- Singleton helpers -----------------------------------------------
+    @classmethod
+    def instance(cls) -> "LendingStateRepository":
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        with cls._instance_lock:
+            cls._instance = None
+
+    # ---- Core API ---------------------------------------------------------
+    def load_intent(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["intents"].get(_identifier(user_id, conversation_id))
+            if not record:
+                return None
+            return copy.deepcopy(record.get("intent"))
+
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.load_intent(user_id, conversation_id)
+        if not session:
+            return None
+        return session.get("intent") or None
+
+    def persist_intent(
+        self,
+        user_id: str,
+        conversation_id: str,
+        intent: Dict[str, Any],
+        metadata: Dict[str, Any],
+        done: bool,
+        summary: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
+            now = time.time()
+            if done:
+                self._state["intents"].pop(key, None)
+            else:
+                self._state["intents"][key] = {"intent": copy.deepcopy(intent), "updated_at": now}
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = now
+                self._state["metadata"][key] = meta_copy
+            if done and summary:
+                history = self._state["history"].setdefault(key, [])
+                summary_copy = copy.deepcopy(summary)
+                summary_copy.setdefault("timestamp", now)
+                history.append(summary_copy)
+                self._state["history"][key] = history[-self._history_limit :]
+            return self.get_history(user_id, conversation_id)
+
+        try:
+            if done:
+                if summary:
+                    self._create_history_entry(user_id, conversation_id, summary)
+                self._delete_session(user_id, conversation_id)
+            else:
+                payload = self._session_payload(intent, metadata)
+                self._upsert_session(user_id, conversation_id, payload)
+            return self.get_history(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            return self.persist_intent(user_id, conversation_id, intent, metadata, done, summary)
+
+    def set_metadata(
+        self,
+        user_id: str,
+        conversation_id: str,
+        metadata: Dict[str, Any],
+    ) -> None:
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = time.time()
+                self._state["metadata"][key] = meta_copy
+            else:
+                self._state["metadata"].pop(key, None)
+            return
+
+        try:
+            if not metadata:
+                self._delete_session(user_id, conversation_id)
+                return
+
+            session = self._get_session(user_id, conversation_id)
+            if not self._use_gateway:
+                return self.set_metadata(user_id, conversation_id, metadata)
+            intent = session.get("intent") if session else {}
+            payload = self._session_payload(intent or {}, metadata)
+            self._upsert_session(user_id, conversation_id, payload)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.set_metadata(user_id, conversation_id, metadata)
+
+    def clear_metadata(self, user_id: str, conversation_id: str) -> None:
+        self.set_metadata(user_id, conversation_id, {})
+
+    def clear_intent(self, user_id: str, conversation_id: str) -> None:
+        if not self._use_gateway:
+            self._init_local_store()
+            self._state["intents"].pop(_identifier(user_id, conversation_id), None)
+            self._state["metadata"].pop(_identifier(user_id, conversation_id), None)
+            return
+        try:
+            self._delete_session(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.clear_intent(user_id, conversation_id)
+
+    def get_metadata(self, user_id: str, conversation_id: str) -> Dict[str, Any]:
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["metadata"].get(_identifier(user_id, conversation_id))
+            if not record:
+                return {}
+            entry = copy.deepcopy(record)
+            ts = entry.pop("updated_at", None)
+            if ts is not None:
+                entry["updated_at"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+            return entry
+
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.get_metadata(user_id, conversation_id)
+        if not session:
+            return {}
+
+        intent = session.get("intent") or {}
+        metadata: Dict[str, Any] = {
+            "event": session.get("event"),
+            "status": session.get("status"),
+            "missing_fields": session.get("missingFields") or [],
+            "next_field": session.get("nextField"),
+            "pending_question": session.get("pendingQuestion"),
+            "choices": session.get("choices") or [],
+            "error": session.get("errorMessage"),
+            "user_id": user_id,
+            "conversation_id": conversation_id,
+        }
+        metadata["action"] = intent.get("action")
+        metadata["network"] = intent.get("network")
+        metadata["asset"] = intent.get("asset")
+        metadata["amount"] = intent.get("amount")
+
+        history = self.get_history(user_id, conversation_id)
+        if history:
+            metadata["history"] = history
+
+        updated_at = session.get("updatedAt")
+        if updated_at:
+            metadata["updated_at"] = updated_at
+
+        return metadata
+
+    def get_history(
+        self,
+        user_id: str,
+        conversation_id: str,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        if not self._use_gateway:
+            key = _identifier(user_id, conversation_id)
+            history = self._state["history"].get(key, [])
+            effective = limit or self._history_limit
+            result: List[Dict[str, Any]] = []
+            for item in sorted(history, key=lambda entry: entry.get("timestamp", 0), reverse=True)[:effective]:
+                entry = copy.deepcopy(item)
+                ts = entry.get("timestamp")
+                if ts is not None:
+                    entry["timestamp"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+                result.append(entry)
+            return result
+
+        effective_limit = limit or self._history_limit
+        try:
+            result = self._client.list(
+                LENDING_HISTORY_ENTITY,
+                {
+                    "where": {"userId": user_id, "conversationId": conversation_id},
+                    "orderBy": {"recordedAt": "desc"},
+                    "take": effective_limit,
+                },
+            )
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return []
+            self._handle_gateway_failure(exc)
+            return self.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            self._logger.warning("Invalid lending history response from gateway; falling back to local store.")
+            self._fallback_to_local_store()
+            return self.get_history(user_id, conversation_id, limit)
+        data = result.get("data", []) if isinstance(result, dict) else []
+        history: List[Dict[str, Any]] = []
+        for entry in data:
+            history.append(
+                {
+                    "status": entry.get("status"),
+                    "action": entry.get("action"),
+                    "network": entry.get("network"),
+                    "asset": entry.get("asset"),
+                    "amount": entry.get("amount"),
+                    "error": entry.get("errorMessage"),
+                    "timestamp": entry.get("recordedAt"),
+                }
+            )
+        return history
+
+    # ---- Gateway helpers --------------------------------------------------
+    def _get_session(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            return self._client.get(LENDING_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return None
+            self._handle_gateway_failure(exc)
+            return None
+
+    def _delete_session(self, user_id: str, conversation_id: str) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            self._client.delete(LENDING_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                self._handle_gateway_failure(exc)
+                raise
+
+    def _upsert_session(
+        self,
+        user_id: str,
+        conversation_id: str,
+        data: Dict[str, Any],
+    ) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        payload = {**data, "updatedAt": _utc_now_iso()}
+        try:
+            self._client.update(LENDING_SESSION_ENTITY, identifier, payload)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                self._handle_gateway_failure(exc)
+                raise
+            create_payload = {
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "tenantId": self._tenant_id(),
+                **payload,
+            }
+            try:
+                self._client.create(LENDING_SESSION_ENTITY, create_payload)
+            except PanoramaGatewayError as create_exc:
+                if create_exc.status_code == 409:
+                    return
+                if create_exc.status_code == 404:
+                    self._handle_gateway_failure(create_exc)
+                    raise
+                self._handle_gateway_failure(create_exc)
+                raise
+
+    def _create_history_entry(
+        self,
+        user_id: str,
+        conversation_id: str,
+        summary: Dict[str, Any],
+    ) -> None:
+        history_payload = {
+            "userId": user_id,
+            "conversationId": conversation_id,
+            "status": summary.get("status"),
+            "action": summary.get("action"),
+            "network": summary.get("network"),
+            "asset": summary.get("asset"),
+            "amount": _as_float(summary.get("amount")),
+            "errorMessage": summary.get("error"),
+            "recordedAt": _utc_now_iso(),
+            "tenantId": self._tenant_id(),
+        }
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._logger.debug(
+                "Persisting lending history for user=%s conversation=%s payload=%s",
+                user_id,
+                conversation_id,
+                history_payload,
+            )
+        try:
+            self._client.create(LENDING_HISTORY_ENTITY, history_payload)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                self._handle_gateway_failure(exc)
+                raise
+            elif exc.status_code != 409:
+                self._handle_gateway_failure(exc)
+                raise
+
+    @staticmethod
+    def _session_payload(intent: Dict[str, Any], metadata: Dict[str, Any]) -> Dict[str, Any]:
+        missing = metadata.get("missing_fields") or []
+        if not isinstance(missing, list):
+            missing = list(missing)
+        return {
+            "status": metadata.get("status"),
+            "event": metadata.get("event"),
+            "intent": intent,
+            "missingFields": missing,
+            "nextField": metadata.get("next_field"),
+            "pendingQuestion": metadata.get("pending_question"),
+            "choices": metadata.get("choices"),
+            "errorMessage": metadata.get("error"),
+            "historyCursor": metadata.get("history_cursor") or 0,
+        }

src/agents/lending/tools.py

@@ -0,0 +1,388 @@
+"""Lending tools that manage a conversational lending intent."""
+
+from __future__ import annotations
+
+import logging
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, List, Optional
+
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field, field_validator
+
+from src.agents.metadata import metadata
+from src.agents.lending.config import LendingConfig
+from src.agents.lending.intent import LendingIntent, _to_decimal
+from src.agents.lending.storage import LendingStateRepository
+
+
+# ---------- Helpers ----------
+_STORE = LendingStateRepository.instance()
+logger = logging.getLogger(__name__)
+
+
+# ---------- Lending session context ----------
+_CURRENT_SESSION: ContextVar[tuple[str, str]] = ContextVar(
+    "_current_lending_session",
+    default=("", ""),
+)
+
+
+def set_current_lending_session(user_id: Optional[str], conversation_id: Optional[str]) -> None:
+    """Store the active lending session for tool calls executed by the agent."""
+
+    resolved_user = (user_id or "").strip()
+    resolved_conversation = (conversation_id or "").strip()
+    if not resolved_user:
+        raise ValueError("lending_agent requires 'user_id' to identify the lending session.")
+    if not resolved_conversation:
+        raise ValueError("lending_agent requires 'conversation_id' to identify the lending session.")
+    _CURRENT_SESSION.set((resolved_user, resolved_conversation))
+
+
+@contextmanager
+def lending_session(user_id: Optional[str], conversation_id: Optional[str]):
+    """Context manager that guarantees session scoping for lending tool calls."""
+
+    set_current_lending_session(user_id, conversation_id)
+    try:
+        yield
+    finally:
+        clear_current_lending_session()
+
+
+def clear_current_lending_session() -> None:
+    """Reset the active lending session after the agent finishes handling a message."""
+
+    _CURRENT_SESSION.set(("", ""))
+
+
+def _resolve_session(user_id: Optional[str], conversation_id: Optional[str]) -> tuple[str, str]:
+    active_user, active_conversation = _CURRENT_SESSION.get()
+    resolved_user = (user_id or active_user or "").strip()
+    resolved_conversation = (conversation_id or active_conversation or "").strip()
+    if not resolved_user:
+        raise ValueError("user_id is required for lending operations.")
+    if not resolved_conversation:
+        raise ValueError("conversation_id is required for lending operations.")
+    return resolved_user, resolved_conversation
+
+
+def _load_intent(user_id: str, conversation_id: str) -> LendingIntent:
+    stored = _STORE.load_intent(user_id, conversation_id)
+    if stored:
+        intent = LendingIntent.from_dict(stored)
+        intent.user_id = user_id
+        intent.conversation_id = conversation_id
+        return intent
+    return LendingIntent(user_id=user_id, conversation_id=conversation_id)
+
+
+# ---------- Pydantic input schema ----------
+class UpdateLendingIntentInput(BaseModel):
+    user_id: Optional[str] = Field(
+        default=None,
+        description="Stable ID for the end user / chat session. Optional if context manager is set.",
+    )
+    conversation_id: Optional[str] = Field(
+        default=None,
+        description="Conversation identifier to scope lending intents within a user.",
+    )
+    action: Optional[str] = None
+    network: Optional[str] = None
+    asset: Optional[str] = None
+    amount: Optional[Decimal] = Field(None, gt=Decimal("0"))
+
+    @field_validator("network", mode="before")
+    @classmethod
+    def _norm_network(cls, value: Optional[str]) -> Optional[str]:
+        return value.lower() if isinstance(value, str) else value
+
+    @field_validator("asset", mode="before")
+    @classmethod
+    def _norm_asset(cls, value: Optional[str]) -> Optional[str]:
+        return value.upper() if isinstance(value, str) else value
+    
+    @field_validator("action", mode="before")
+    @classmethod
+    def _norm_action(cls, value: Optional[str]) -> Optional[str]:
+        return value.lower() if isinstance(value, str) else value
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _norm_amount(cls, value):
+        if value is None or isinstance(value, Decimal):
+            return value
+        decimal_value = _to_decimal(value)
+        if decimal_value is None:
+            raise ValueError("Amount must be a number.")
+        return decimal_value
+
+
+# ---------- Validation utilities ----------
+def _validate_network(network: Optional[str]) -> Optional[str]:
+    if network is None:
+        return None
+    return LendingConfig.validate_network(network)
+
+
+def _validate_asset(asset: Optional[str], network: Optional[str]) -> Optional[str]:
+    if asset is None:
+        return None
+    if network is None:
+        raise ValueError("Please provide the network before choosing an asset.")
+    return LendingConfig.validate_asset(asset, network)
+
+def _validate_action(action: Optional[str]) -> Optional[str]:
+    if action is None:
+        return None
+    return LendingConfig.validate_action(action)
+
+
+# ---------- Output helpers ----------
+def _store_lending_metadata(
+    intent: LendingIntent,
+    ask: Optional[str],
+    done: bool,
+    error: Optional[str],
+    choices: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    intent.touch()
+    missing = intent.missing_fields()
+    next_field = missing[0] if missing else None
+    meta: Dict[str, Any] = {
+        "event": "lending_intent_ready" if done else "lending_intent_pending",
+        "status": "ready" if done else "collecting",
+        "action": intent.action,
+        "network": intent.network,
+        "asset": intent.asset,
+        "amount": intent.amount_as_str(),
+        "user_id": intent.user_id,
+        "conversation_id": intent.conversation_id,
+        "missing_fields": missing,
+        "next_field": next_field,
+        "pending_question": ask,
+        "choices": list(choices or []),
+        "error": error,
+    }
+    summary = intent.to_summary("ready" if done else "collecting", error=error) if done else None
+    history = _STORE.persist_intent(
+        intent.user_id,
+        intent.conversation_id,
+        intent.to_dict(),
+        meta,
+        done=done,
+        summary=summary,
+    )
+    if history:
+        meta["history"] = history
+    metadata.set_lending_agent(meta, intent.user_id, intent.conversation_id)
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "Lending metadata stored for user=%s conversation=%s done=%s error=%s meta=%s",
+            intent.user_id,
+            intent.conversation_id,
+            done,
+            error,
+            meta,
+        )
+    return meta
+
+
+def _build_next_action(meta: Dict[str, Any]) -> Dict[str, Any]:
+    if meta.get("status") == "ready":
+        return {
+            "type": "complete",
+            "prompt": None,
+            "field": None,
+            "choices": [],
+        }
+    return {
+        "type": "collect_field",
+        "prompt": meta.get("pending_question"),
+        "field": meta.get("next_field"),
+        "choices": meta.get("choices", []),
+    }
+
+
+def _response(
+    intent: LendingIntent,
+    ask: Optional[str],
+    choices: Optional[List[str]] = None,
+    done: bool = False,
+    error: Optional[str] = None,
+) -> Dict[str, Any]:
+    meta = _store_lending_metadata(intent, ask, done, error, choices)
+
+    payload: Dict[str, Any] = {
+        "event": meta.get("event"),
+        "intent": intent.to_public(),
+        "ask": ask,
+        "choices": choices or [],
+        "error": error,
+        "next_action": _build_next_action(meta),
+        "history": meta.get("history", []),
+    }
+
+    if done:
+        payload["metadata"] = {
+            key: meta.get(key)
+            for key in (
+                "event",
+                "status",
+                "action",
+                "network",
+                "asset",
+                "amount",
+                "user_id",
+                "conversation_id",
+                "history",
+            )
+            if meta.get(key) is not None
+        }
+    return payload
+
+
+# ---------- Core tool ----------
+@tool("update_lending_intent", args_schema=UpdateLendingIntentInput)
+def update_lending_intent_tool(
+    user_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    action: Optional[str] = None,
+    network: Optional[str] = None,
+    asset: Optional[str] = None,
+    amount: Optional[Decimal] = None,
+):
+    """Update the lending intent and surface the next question or final metadata.
+
+    Call this tool whenever the user provides new lending details. Supply only the
+    fields that were mentioned in the latest message (leave the others as None)
+    and keep calling it until the response event becomes 'lending_intent_ready'.
+    """
+
+    resolved_user, resolved_conversation = _resolve_session(user_id, conversation_id)
+    intent = _load_intent(resolved_user, resolved_conversation)
+    intent.user_id = resolved_user
+    intent.conversation_id = resolved_conversation
+
+    try:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "update_lending_intent_tool input user=%s conversation=%s action=%s network=%s "
+                "asset=%s amount=%s",
+                user_id,
+                conversation_id,
+                action,
+                network,
+                asset,
+                amount,
+            )
+
+        if action is not None:
+            intent.action = _validate_action(action)
+
+        if network is not None:
+            canonical_net = _validate_network(network)
+            if canonical_net != intent.network:
+                intent.network = canonical_net
+                # Re-validate asset if network changed
+                if intent.asset:
+                    try:
+                        LendingConfig.validate_asset(intent.asset, canonical_net)
+                    except ValueError:
+                        intent.asset = None
+        
+        if intent.action is None:
+             return _response(
+                intent,
+                "What would you like to do? (supply, borrow, repay, withdraw)",
+                LendingConfig.SUPPORTED_ACTIONS,
+            )
+
+        if intent.network is None and network is not None:
+             # User tried to set network but maybe it was invalid or just checking
+             pass
+
+        if intent.network is None:
+             return _response(
+                intent,
+                "On which network?",
+                LendingConfig.list_networks(),
+            )
+
+        if asset is not None:
+            intent.asset = _validate_asset(asset, intent.network)
+
+        if intent.asset is None:
+            return _response(
+                intent,
+                f"Which asset on {intent.network}?",
+                LendingConfig.list_assets(intent.network),
+            )
+
+        if amount is not None:
+            intent.amount = amount # Basic validation done in pydantic
+
+        if intent.amount is None:
+            return _response(intent, f"How much {intent.asset}?")
+
+    except ValueError as exc:
+        message = str(exc)
+        if logger.isEnabledFor(logging.INFO):
+            logger.info(
+                "Lending intent validation issue for user=%s conversation=%s: %s",
+                intent.user_id,
+                intent.conversation_id,
+                message,
+            )
+        return _response(intent, "Please correct the input.", error=message)
+    except Exception as exc:
+        logger.exception(
+            "Unexpected error updating lending intent for user=%s conversation=%s",
+            intent.user_id,
+            intent.conversation_id,
+        )
+        return _response(intent, "Please try again with the lending details.", error=str(exc))
+
+    response = _response(intent, ask=None, done=True)
+    return response
+
+
+class ListLendingAssetsInput(BaseModel):
+    network: str
+
+    @field_validator("network", mode="before")
+    @classmethod
+    def _norm_network(cls, value: str) -> str:
+        return value.lower() if isinstance(value, str) else value
+
+
+@tool("list_lending_assets", args_schema=ListLendingAssetsInput)
+def list_lending_assets_tool(network: str):
+    """List the supported lending assets for a given network."""
+
+    try:
+        canonical = _validate_network(network)
+        assets = LendingConfig.list_assets(canonical)
+        return {
+            "network": canonical,
+            "assets": assets,
+        }
+    except ValueError as exc:
+        return {
+            "error": str(exc),
+            "choices": LendingConfig.list_networks(),
+        }
+
+
+@tool("list_lending_networks")
+def list_lending_networks_tool():
+    """List supported lending networks."""
+
+    return {"networks": LendingConfig.list_networks()}
+
+
+def get_tools():
+    return [update_lending_intent_tool, list_lending_assets_tool, list_lending_networks_tool]

src/agents/metadata.py

@@ -3,12 +3,16 @@ from __future__ import annotations
 from typing import Any, Dict
 
 from src.agents.swap.storage import SwapStateRepository
+from src.agents.dca.storage import DcaStateRepository
+from src.agents.lending.storage import LendingStateRepository
 
 
 class Metadata:
     def __init__(self):
         self.crypto_data_agent: Dict[str, Any] = {}
         self._swap_repo = SwapStateRepository.instance()
+        self._dca_repo = DcaStateRepository.instance()
+        self._lending_repo = LendingStateRepository.instance()
 
     def get_crypto_data_agent(self):
         return self.crypto_data_agent
@@ -37,6 +41,43 @@ class Metadata:
             # Ignore clears when identity is missing; no actionable state to update.
             return
 
+    def get_dca_agent(self, user_id: str | None = None, conversation_id: str | None = None):
+        try:
+            return self._dca_repo.get_metadata(user_id, conversation_id)
+        except ValueError:
+            return {}
+
+    def set_dca_agent(
+        self,
+        dca_agent: Dict[str, Any] | None,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+    ):
+        try:
+            if dca_agent:
+                self._dca_repo.set_metadata(user_id, conversation_id, dca_agent)
+            else:
+                self._dca_repo.clear_metadata(user_id, conversation_id)
+        except ValueError:
+            return
+
+    def clear_dca_agent(self, user_id: str | None = None, conversation_id: str | None = None) -> None:
+        try:
+            self._dca_repo.clear_metadata(user_id, conversation_id)
+        except ValueError:
+            return
+
+    def get_dca_history(
+        self,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+        limit: int | None = None,
+    ):
+        try:
+            return self._dca_repo.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            return []
+
     def get_swap_history(
         self,
         user_id: str | None = None,
@@ -48,5 +89,42 @@ class Metadata:
         except ValueError:
             return []
 
+    def get_lending_agent(self, user_id: str | None = None, conversation_id: str | None = None):
+        try:
+            return self._lending_repo.get_metadata(user_id, conversation_id)
+        except ValueError:
+            return {}
+
+    def set_lending_agent(
+        self,
+        lending_agent: Dict[str, Any] | None,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+    ):
+        try:
+            if lending_agent:
+                self._lending_repo.set_metadata(user_id, conversation_id, lending_agent)
+            else:
+                self._lending_repo.clear_metadata(user_id, conversation_id)
+        except ValueError:
+            return
+
+    def clear_lending_agent(self, user_id: str | None = None, conversation_id: str | None = None) -> None:
+        try:
+            self._lending_repo.clear_metadata(user_id, conversation_id)
+        except ValueError:
+            return
+
+    def get_lending_history(
+        self,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+        limit: int | None = None,
+    ):
+        try:
+            return self._lending_repo.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            return []
+
 
 metadata = Metadata()

src/agents/supervisor/agent.py

@@ -13,8 +13,12 @@ from src.agents.crypto_data.agent import CryptoDataAgent
 from src.agents.database.agent import DatabaseAgent
 from src.agents.default.agent import DefaultAgent
 from src.agents.swap.agent import SwapAgent
+from src.agents.swap.config import SwapConfig
 from src.agents.swap.tools import swap_session
 from src.agents.swap.prompt import SWAP_AGENT_SYSTEM_PROMPT
+from src.agents.dca.agent import DcaAgent
+from src.agents.dca.tools import dca_session
+from src.agents.dca.prompt import DCA_AGENT_SYSTEM_PROMPT
 from src.agents.search.agent import SearchAgent
 from src.agents.database.client import is_database_available
 
@@ -64,6 +68,13 @@ class Supervisor:
             "- swap_agent: Handles swap operations on the Avalanche network and any other swap question related.\n"
         )
 
+        dcaAgent = DcaAgent(llm)
+        self.dca_agent = dcaAgent.agent
+        agents.append(self.dca_agent)
+        available_agents_text += (
+            "- dca_agent: Plans DCA swap workflows, consulting strategy docs, validating parameters, and confirming automation metadata.\n"
+        )
+
         searchAgent = SearchAgent(llm)
         self.search_agent = searchAgent.agent
         agents.append(self.search_agent)
@@ -76,8 +87,8 @@ class Supervisor:
         agents.append(self.default_agent)
 
         # Track known agent names for response extraction
-        self.known_agent_names = {"crypto_agent", "database_agent", "swap_agent", "search_agent", "default_agent"}
-        self.specialized_agents = {"crypto_agent", "database_agent", "swap_agent", "search_agent"}
+        self.known_agent_names = {"crypto_agent", "database_agent", "swap_agent", "dca_agent", "search_agent", "default_agent"}
+        self.specialized_agents = {"crypto_agent", "database_agent", "swap_agent", "dca_agent", "search_agent"}
         self.failure_markers = (
             "cannot fulfill",
             "can't fulfill",
@@ -177,11 +188,18 @@ Examples of swap queries to delegate:
 - What are the available tokens for swapping?
 - I want to swap 100 USD for AVAX
 
+Examples of dca queries to delegate:
+- Help me schedule a daily DCA from USDC to AVAX
+- Suggest a weekly swap DCA strategy
+- I want to automate a monthly swap from token A to token B
+
 When a swap conversation is already underway (the user is still providing swap
 details or the swap_agent requested follow-up information), keep routing those
 messages to the swap_agent until it has gathered every field and signals the
 swap intent is ready.
 
+When a DCA conversation is already underway (the user is reviewing strategy recommendations or adjusting schedule parameters), keep routing messages to the dca_agent until the workflow is confirmed or cancelled.
+
 {database_examples}
 
 {search_examples}
@@ -202,6 +220,8 @@ Examples of general queries to handle directly:
 
         self.app = self.supervisor.compile()
 
+        self._swap_network_terms, self._swap_token_terms = self._build_swap_detection_terms()
+
     def _is_handoff_text(self, text: str) -> bool:
         if not text:
             return False
@@ -325,6 +345,25 @@ Examples of general queries to handle directly:
         agent, text, messages_out = self._extract_response_from_graph(response)
         return agent, text, messages_out
 
+    def _invoke_dca_agent(self, langchain_messages):
+        scoped_messages = [SystemMessage(content=DCA_AGENT_SYSTEM_PROMPT)]
+        scoped_messages.extend(langchain_messages)
+        try:
+            with dca_session(
+                user_id=self._active_user_id,
+                conversation_id=self._active_conversation_id,
+            ):
+                response = self.dca_agent.invoke({"messages": scoped_messages})
+        except Exception as exc:
+            print(f"Error invoking dca agent directly: {exc}")
+            return None
+
+        if not response:
+            return None
+
+        agent, text, messages_out = self._extract_response_from_graph(response)
+        return agent, text, messages_out
+
     def _extract_response_from_graph(self, response: Any) -> Tuple[str, str, list]:
         messages_out = response.get("messages", []) if isinstance(response, dict) else []
         final_response = None
@@ -415,6 +454,45 @@ Examples of general queries to handle directly:
             fallback_agent = "search_agent"
         return fallback_agent, fallback_text, fallback_messages
 
+    def _detect_pending_followups(self, messages: List[Any]) -> tuple[bool, bool]:
+        awaiting_swap = False
+        awaiting_dca = False
+        def _get_entry_value(entry: Any, dict_keys: tuple[str, ...], attr_name: str) -> Any:
+            """Support both camelCase (gateway) and snake_case (local) message fields."""
+            if isinstance(entry, dict):
+                for key in dict_keys:
+                    if key in entry:
+                        return entry.get(key)
+                return None
+            return getattr(entry, attr_name, None)
+
+        for entry in reversed(messages):
+            role_raw = _get_entry_value(entry, ("role", "Role"), "role")
+            agent_label_raw = _get_entry_value(entry, ("agent_name", "agentName"), "agent_name")
+            action_type_raw = _get_entry_value(entry, ("action_type", "actionType"), "action_type")
+            requires_action_raw = _get_entry_value(
+                entry,
+                ("requires_action", "requiresAction"),
+                "requires_action",
+            )
+            metadata_payload = _get_entry_value(entry, ("metadata",), "metadata") or {}
+
+            role = str(role_raw or "").lower()
+            if role != "assistant":
+                continue
+            agent_label = str(agent_label_raw or "").lower()
+            action_type = str(action_type_raw or "").lower()
+            requires_action = bool(requires_action_raw)
+            status = str((metadata_payload.get("status") if isinstance(metadata_payload, dict) else "") or "").lower()
+
+            if requires_action and status != "ready":
+                if action_type == "swap" or "swap" in agent_label:
+                    awaiting_swap = True
+                if action_type == "dca" or "dca" in agent_label:
+                    awaiting_dca = True
+            break
+        return awaiting_swap, awaiting_dca
+
     def _build_metadata(self, agent_name: str, messages_out) -> dict:
         if agent_name == "swap_agent":
             swap_meta = metadata.get_swap_agent(
@@ -432,6 +510,22 @@ Examples of general queries to handle directly:
                 else:
                     swap_meta = swap_meta.copy()
             return swap_meta if swap_meta else {}
+        if agent_name == "dca_agent":
+            dca_meta = metadata.get_dca_agent(
+                user_id=self._active_user_id,
+                conversation_id=self._active_conversation_id,
+            )
+            if dca_meta:
+                history = metadata.get_dca_history(
+                    user_id=self._active_user_id,
+                    conversation_id=self._active_conversation_id,
+                )
+                if history:
+                    dca_meta = dca_meta.copy()
+                    dca_meta.setdefault("history", history)
+                else:
+                    dca_meta = dca_meta.copy()
+            return dca_meta if dca_meta else {}
         if agent_name == "crypto_agent":
             tool_meta = self._collect_tool_metadata(messages_out)
             if tool_meta:
@@ -439,6 +533,50 @@ Examples of general queries to handle directly:
             return metadata.get_crypto_data_agent() or {}
         return {}
 
+    def _build_swap_detection_terms(self) -> tuple[set[str], set[str]]:
+        networks: set[str] = set()
+        tokens: set[str] = set()
+        try:
+            for net in SwapConfig.list_networks():
+                lowered = net.lower()
+                networks.add(lowered)
+                try:
+                    for token in SwapConfig.list_tokens(net):
+                        tokens.add(token.lower())
+                except ValueError:
+                    continue
+        except Exception:
+            return set(), set()
+        return networks, tokens
+
+    def _is_swap_like_request(self, messages: List[ChatMessage]) -> bool:
+        for msg in reversed(messages):
+            if msg.get("role") != "user":
+                continue
+            content = (msg.get("content") or "").strip()
+            if not content:
+                continue
+            lowered = content.lower()
+            swap_keywords = (
+                "swap",
+                "swapping",
+                "exchange",
+                "convert",
+                "trade",
+            )
+            if not any(keyword in lowered for keyword in swap_keywords):
+                return False
+            if any(term and term in lowered for term in self._swap_network_terms):
+                return True
+            if any(term and term in lowered for term in self._swap_token_terms):
+                return True
+            if "token" in lowered or any(ch.isdigit() for ch in lowered):
+                return True
+            # Default to True if the user explicitly mentioned swap-related keywords,
+            # even if they haven't provided networks/tokens yet.
+            return True
+        return False
+
     def invoke(
         self,
         messages: List[ChatMessage],
@@ -447,7 +585,7 @@ Examples of general queries to handle directly:
     ) -> dict:
         self._active_user_id = user_id
         self._active_conversation_id = conversation_id
-        swap_state = metadata.get_swap_agent(user_id=user_id, conversation_id=conversation_id)
+        awaiting_swap, awaiting_dca = self._detect_pending_followups(messages)
 
         langchain_messages = []
         for msg in messages:
@@ -463,6 +601,66 @@ Examples of general queries to handle directly:
             SystemMessage(content="Always respond in English, regardless of the user's language."),
         )
 
+        dca_state = metadata.get_dca_agent(user_id=user_id, conversation_id=conversation_id)
+        swap_state = metadata.get_swap_agent(user_id=user_id, conversation_id=conversation_id)
+
+        if not swap_state and self._is_swap_like_request(messages):
+            swap_result = self._invoke_swap_agent(langchain_messages)
+            if swap_result:
+                final_agent, cleaned_response, messages_out = swap_result
+                meta = self._build_metadata(final_agent, messages_out)
+                self._active_user_id = None
+                self._active_conversation_id = None
+                return {
+                    "messages": messages_out,
+                    "agent": final_agent,
+                    "response": cleaned_response or "Sorry, no meaningful response was returned.",
+                    "metadata": meta,
+                }
+
+        in_progress_statuses = {"consulting", "recommendation", "confirmation"}
+
+        if dca_state and dca_state.get("status") in in_progress_statuses:
+            dca_result = self._invoke_dca_agent(langchain_messages)
+            if dca_result:
+                final_agent, cleaned_response, messages_out = dca_result
+                meta = self._build_metadata(final_agent, messages_out)
+                self._active_user_id = None
+                self._active_conversation_id = None
+                return {
+                    "messages": messages_out,
+                    "agent": final_agent,
+                    "response": cleaned_response or "Sorry, no meaningful response was returned.",
+                    "metadata": meta,
+                }
+            stage = dca_state.get("status")
+            next_field = dca_state.get("next_field")
+            pending_question = dca_state.get("pending_question")
+            guidance_parts = [
+                "There is an in-progress DCA planning session for this conversation.",
+                "Keep routing messages to the dca_agent until the workflow is confirmed or the user cancels.",
+            ]
+            if stage:
+                guidance_parts.append(f"The current stage is: {stage}.")
+            if next_field:
+                guidance_parts.append(f"The next field to collect is: {next_field}.")
+            if pending_question:
+                guidance_parts.append(f"Continue the DCA flow by asking: {pending_question}")
+            langchain_messages.insert(0, SystemMessage(content=" ".join(guidance_parts)))
+        elif awaiting_dca:
+            dca_result = self._invoke_dca_agent(langchain_messages)
+            if dca_result:
+                final_agent, cleaned_response, messages_out = dca_result
+                meta = self._build_metadata(final_agent, messages_out)
+                self._active_user_id = None
+                self._active_conversation_id = None
+                return {
+                    "messages": messages_out,
+                    "agent": final_agent,
+                    "response": cleaned_response or "Sorry, no meaningful response was returned.",
+                    "metadata": meta,
+                }
+
         if swap_state and swap_state.get("status") == "collecting":
             swap_result = self._invoke_swap_agent(langchain_messages)
             if swap_result:
@@ -489,11 +687,25 @@ Examples of general queries to handle directly:
                 guidance_parts.append(f"Continue the swap flow by asking: {pending_question}")
             guidance_text = " ".join(guidance_parts)
             langchain_messages.insert(0, SystemMessage(content=guidance_text))
+        elif awaiting_swap:
+            swap_result = self._invoke_swap_agent(langchain_messages)
+            if swap_result:
+                final_agent, cleaned_response, messages_out = swap_result
+                meta = self._build_metadata(final_agent, messages_out)
+                self._active_user_id = None
+                self._active_conversation_id = None
+                return {
+                    "messages": messages_out,
+                    "agent": final_agent,
+                    "response": cleaned_response or "Sorry, no meaningful response was returned.",
+                    "metadata": meta,
+                }
 
         try:
             with swap_session(user_id=user_id, conversation_id=conversation_id):
-                response = self.app.invoke({"messages": langchain_messages})
-                print("DEBUG: response", response)
+                with dca_session(user_id=user_id, conversation_id=conversation_id):
+                    response = self.app.invoke({"messages": langchain_messages})
+                    print("DEBUG: response", response)
         except Exception as e:
             print(f"Error in Supervisor: {e}")
             return {

src/agents/swap/storage.py

@@ -1,45 +1,89 @@
-"""Persistent storage for swap intents and metadata."""
+"""Gateway-backed storage for swap intents with local fallback."""
 from __future__ import annotations
 
 import copy
-import json
-import os
 import time
+import logging
 from datetime import datetime, timezone
-from pathlib import Path
 from threading import Lock
 from typing import Any, Dict, List, Optional
 
-_STATE_TEMPLATE: Dict[str, Dict[str, Any]] = {
-    "intents": {},
-    "metadata": {},
-    "history": {},
-}
+from src.integrations.panorama_gateway import (
+    PanoramaGatewayClient,
+    PanoramaGatewayError,
+    PanoramaGatewaySettings,
+    get_panorama_settings,
+)
+
+SWAP_SESSION_ENTITY = "swap-sessions"
+SWAP_HISTORY_ENTITY = "swap-histories"
+
+
+def _utc_now_iso() -> str:
+    return datetime.utcnow().replace(tzinfo=timezone.utc).isoformat()
+
+
+def _identifier(user_id: str, conversation_id: str) -> str:
+    return f"{user_id}:{conversation_id}"
+
+
+def _as_float(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
 
 
 class SwapStateRepository:
-    """File-backed storage for swap agent state with TTL and history support."""
+    """Stores swap agent state via Panorama's gateway or an in-memory fallback."""
 
     _instance: "SwapStateRepository" | None = None
     _instance_lock: Lock = Lock()
 
     def __init__(
         self,
-        path: Optional[Path] = None,
-        ttl_seconds: int = 3600,
+        *,
+        client: PanoramaGatewayClient | None = None,
+        settings: PanoramaGatewaySettings | None = None,
         history_limit: int = 10,
     ) -> None:
-        env_path = os.getenv("SWAP_STATE_PATH")
-        default_path = Path(__file__).with_name("swap_state.json")
-        self._path = Path(path or env_path or default_path)
-        self._ttl_seconds = ttl_seconds
+        self._logger = logging.getLogger(__name__)
         self._history_limit = history_limit
-        self._lock = Lock()
-        self._state: Dict[str, Dict[str, Any]] = copy.deepcopy(_STATE_TEMPLATE)
-        self._ensure_parent()
-        with self._lock:
-            self._load_locked()
+        try:
+            self._settings = settings or get_panorama_settings()
+            self._client = client or PanoramaGatewayClient(self._settings)
+            self._use_gateway = True
+        except ValueError:
+            # PANORAMA_GATEWAY_URL or JWT secrets not configured – fall back to local store.
+            self._settings = None
+            self._client = None
+            self._use_gateway = False
+        self._init_local_store()
+
+    def _init_local_store(self) -> None:
+        if not hasattr(self, "_state"):
+            self._state = {"intents": {}, "metadata": {}, "history": {}}
+
+    def _tenant_id(self) -> str:
+        return self._settings.tenant_id if self._settings else "tenant-agent"
 
+    def _fallback_to_local_store(self) -> None:
+        if self._use_gateway:
+            self._logger.warning("Panorama gateway unavailable for swap state; switching to in-memory fallback.")
+        self._use_gateway = False
+        self._init_local_store()
+
+    def _handle_gateway_failure(self, exc: PanoramaGatewayError) -> None:
+        self._logger.warning(
+            "Panorama gateway error (%s) for swap repository: %s",
+            getattr(exc, "status_code", "unknown"),
+            getattr(exc, "payload", exc),
+        )
+        self._fallback_to_local_store()
+
+    # ---- Singleton helpers -----------------------------------------------
     @classmethod
     def instance(cls) -> "SwapStateRepository":
         if cls._instance is None:
@@ -53,93 +97,22 @@ class SwapStateRepository:
         with cls._instance_lock:
             cls._instance = None
 
-    def _ensure_parent(self) -> None:
-        try:
-            self._path.parent.mkdir(parents=True, exist_ok=True)
-        except OSError:
-            pass
-
-    def _load_locked(self) -> None:
-        if not self._path.exists():
-            self._state = copy.deepcopy(_STATE_TEMPLATE)
-            return
-        try:
-            data = json.loads(self._path.read_text())
-        except Exception:
-            self._state = copy.deepcopy(_STATE_TEMPLATE)
-            return
-        if not isinstance(data, dict):
-            self._state = copy.deepcopy(_STATE_TEMPLATE)
-            return
-        state = copy.deepcopy(_STATE_TEMPLATE)
-        for key in state:
-            if isinstance(data.get(key), dict):
-                state[key] = data[key]
-        self._state = state
-
-    def _persist_locked(self) -> None:
-        self._ensure_parent()
-        tmp_path = self._path.with_suffix(".tmp")
-        payload = json.dumps(self._state, ensure_ascii=False, indent=2)
-        try:
-            tmp_path.write_text(payload)
-            tmp_path.replace(self._path)
-        except Exception:
-            pass
-
-    @staticmethod
-    def _normalize_identifier(value: Optional[str], label: str) -> str:
-        candidate = (value or "").strip()
-        if not candidate:
-            raise ValueError(f"{label} is required for swap state operations.")
-        return candidate
-
-    def _key(self, user_id: Optional[str], conversation_id: Optional[str]) -> str:
-        user = self._normalize_identifier(user_id, "user_id")
-        conversation = self._normalize_identifier(conversation_id, "conversation_id")
-        return f"{user}::{conversation}"
-
-    def _purge_locked(self) -> None:
-        if self._ttl_seconds <= 0:
-            return
-        cutoff = time.time() - self._ttl_seconds
-        intents = self._state["intents"]
-        metadata = self._state["metadata"]
-        stale_keys = [
-            key for key, record in intents.items() if record.get("updated_at", 0) < cutoff
-        ]
-        for key in stale_keys:
-            intents.pop(key, None)
-            metadata.pop(key, None)
-
-    @staticmethod
-    def _format_timestamp(value: float) -> str:
-        return datetime.fromtimestamp(value, tz=timezone.utc).isoformat()
-
-    def _history_unlocked(self, key: str, limit: Optional[int] = None) -> List[Dict[str, Any]]:
-        history = self._state["history"].get(key, [])
-        sorted_history = sorted(history, key=lambda item: item.get("timestamp", 0), reverse=True)
-        effective_limit = limit or self._history_limit
-        if effective_limit:
-            sorted_history = sorted_history[:effective_limit]
-        results: List[Dict[str, Any]] = []
-        for item in sorted_history:
-            entry = copy.deepcopy(item)
-            ts = entry.get("timestamp")
-            if ts is not None:
-                entry["timestamp"] = self._format_timestamp(float(ts))
-            results.append(entry)
-        return results
-
+    # ---- Core API ---------------------------------------------------------
     def load_intent(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            self._purge_locked()
-            record = self._state["intents"].get(key)
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["intents"].get(_identifier(user_id, conversation_id))
             if not record:
                 return None
             return copy.deepcopy(record.get("intent"))
 
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.load_intent(user_id, conversation_id)
+        if not session:
+            return None
+        return session.get("intent") or None
+
     def persist_intent(
         self,
         user_id: str,
@@ -149,80 +122,287 @@ class SwapStateRepository:
         done: bool,
         summary: Optional[Dict[str, Any]] = None,
     ) -> List[Dict[str, Any]]:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            self._purge_locked()
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
             now = time.time()
             if done:
                 self._state["intents"].pop(key, None)
             else:
-                self._state["intents"][key] = {
-                    "intent": copy.deepcopy(intent),
-                    "updated_at": now,
-                }
+                self._state["intents"][key] = {"intent": copy.deepcopy(intent), "updated_at": now}
             if metadata:
                 meta_copy = copy.deepcopy(metadata)
                 meta_copy["updated_at"] = now
                 self._state["metadata"][key] = meta_copy
             if done and summary:
-                history = self._state["history"].get(key, [])
+                history = self._state["history"].setdefault(key, [])
                 summary_copy = copy.deepcopy(summary)
                 summary_copy.setdefault("timestamp", now)
                 history.append(summary_copy)
-                self._state["history"][key] = history[-self._history_limit:]
-            try:
-                self._persist_locked()
-            except Exception:
-                pass
-            return self._history_unlocked(key)
-
-    def set_metadata(self, user_id: str, conversation_id: str, metadata: Dict[str, Any]) -> None:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            self._purge_locked()
+                self._state["history"][key] = history[-self._history_limit :]
+            return self.get_history(user_id, conversation_id)
+
+        try:
+            if done:
+                if summary:
+                    self._create_history_entry(user_id, conversation_id, summary)
+                self._delete_session(user_id, conversation_id)
+            else:
+                payload = self._session_payload(intent, metadata)
+                self._upsert_session(user_id, conversation_id, payload)
+            return self.get_history(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            return self.persist_intent(user_id, conversation_id, intent, metadata, done, summary)
+
+    def set_metadata(
+        self,
+        user_id: str,
+        conversation_id: str,
+        metadata: Dict[str, Any],
+    ) -> None:
+        if not self._use_gateway:
+            self._init_local_store()
+            key = _identifier(user_id, conversation_id)
             if metadata:
                 meta_copy = copy.deepcopy(metadata)
                 meta_copy["updated_at"] = time.time()
                 self._state["metadata"][key] = meta_copy
             else:
                 self._state["metadata"].pop(key, None)
-            try:
-                self._persist_locked()
-            except Exception:
-                pass
+            return
+
+        try:
+            if not metadata:
+                self._delete_session(user_id, conversation_id)
+                return
+
+            session = self._get_session(user_id, conversation_id)
+            if not self._use_gateway:
+                return self.set_metadata(user_id, conversation_id, metadata)
+            intent = session.get("intent") if session else {}
+            payload = self._session_payload(intent or {}, metadata)
+            self._upsert_session(user_id, conversation_id, payload)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.set_metadata(user_id, conversation_id, metadata)
 
     def clear_metadata(self, user_id: str, conversation_id: str) -> None:
         self.set_metadata(user_id, conversation_id, {})
 
     def clear_intent(self, user_id: str, conversation_id: str) -> None:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            self._state["intents"].pop(key, None)
-            try:
-                self._persist_locked()
-            except Exception:
-                pass
+        if not self._use_gateway:
+            self._init_local_store()
+            self._state["intents"].pop(_identifier(user_id, conversation_id), None)
+            self._state["metadata"].pop(_identifier(user_id, conversation_id), None)
+            return
+        try:
+            self._delete_session(user_id, conversation_id)
+        except PanoramaGatewayError as exc:
+            self._handle_gateway_failure(exc)
+            self.clear_intent(user_id, conversation_id)
 
     def get_metadata(self, user_id: str, conversation_id: str) -> Dict[str, Any]:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            self._purge_locked()
-            meta = self._state["metadata"].get(key)
-            if not meta:
+        if not self._use_gateway:
+            self._init_local_store()
+            record = self._state["metadata"].get(_identifier(user_id, conversation_id))
+            if not record:
                 return {}
-            entry = copy.deepcopy(meta)
+            entry = copy.deepcopy(record)
             ts = entry.pop("updated_at", None)
             if ts is not None:
-                entry["updated_at"] = self._format_timestamp(float(ts))
+                entry["updated_at"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
             return entry
 
+        session = self._get_session(user_id, conversation_id)
+        if not self._use_gateway:
+            return self.get_metadata(user_id, conversation_id)
+        if not session:
+            return {}
+
+        intent = session.get("intent") or {}
+        metadata: Dict[str, Any] = {
+            "event": session.get("event"),
+            "status": session.get("status"),
+            "missing_fields": session.get("missingFields") or [],
+            "next_field": session.get("nextField"),
+            "pending_question": session.get("pendingQuestion"),
+            "choices": session.get("choices") or [],
+            "error": session.get("errorMessage"),
+            "user_id": user_id,
+            "conversation_id": conversation_id,
+        }
+        metadata["from_network"] = intent.get("from_network")
+        metadata["from_token"] = intent.get("from_token")
+        metadata["to_network"] = intent.get("to_network")
+        metadata["to_token"] = intent.get("to_token")
+        metadata["amount"] = intent.get("amount")
+
+        history = self.get_history(user_id, conversation_id)
+        if history:
+            metadata["history"] = history
+
+        updated_at = session.get("updatedAt")
+        if updated_at:
+            metadata["updated_at"] = updated_at
+
+        return metadata
+
     def get_history(
         self,
         user_id: str,
         conversation_id: str,
         limit: Optional[int] = None,
     ) -> List[Dict[str, Any]]:
-        key = self._key(user_id, conversation_id)
-        with self._lock:
-            return self._history_unlocked(key, limit)
+        if not self._use_gateway:
+            key = _identifier(user_id, conversation_id)
+            history = self._state["history"].get(key, [])
+            effective = limit or self._history_limit
+            result: List[Dict[str, Any]] = []
+            for item in sorted(history, key=lambda entry: entry.get("timestamp", 0), reverse=True)[:effective]:
+                entry = copy.deepcopy(item)
+                ts = entry.get("timestamp")
+                if ts is not None:
+                    entry["timestamp"] = datetime.fromtimestamp(float(ts), tz=timezone.utc).isoformat()
+                result.append(entry)
+            return result
+
+        effective_limit = limit or self._history_limit
+        try:
+            result = self._client.list(
+                SWAP_HISTORY_ENTITY,
+                {
+                    "where": {"userId": user_id, "conversationId": conversation_id},
+                    "orderBy": {"recordedAt": "desc"},
+                    "take": effective_limit,
+                },
+            )
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return []
+            self._handle_gateway_failure(exc)
+            return self.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            self._logger.warning("Invalid swap history response from gateway; falling back to local store.")
+            self._fallback_to_local_store()
+            return self.get_history(user_id, conversation_id, limit)
+        data = result.get("data", []) if isinstance(result, dict) else []
+        history: List[Dict[str, Any]] = []
+        for entry in data:
+            history.append(
+                {
+                    "status": entry.get("status"),
+                    "from_network": entry.get("fromNetwork"),
+                    "from_token": entry.get("fromToken"),
+                    "to_network": entry.get("toNetwork"),
+                    "to_token": entry.get("toToken"),
+                    "amount": entry.get("amount"),
+                    "error": entry.get("errorMessage"),
+                    "timestamp": entry.get("recordedAt"),
+                }
+            )
+        return history
 
+    # ---- Gateway helpers --------------------------------------------------
+    def _get_session(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            return self._client.get(SWAP_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                return None
+            self._handle_gateway_failure(exc)
+            return None
+
+    def _delete_session(self, user_id: str, conversation_id: str) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        try:
+            self._client.delete(SWAP_SESSION_ENTITY, identifier)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                self._handle_gateway_failure(exc)
+                raise
+
+    def _upsert_session(
+        self,
+        user_id: str,
+        conversation_id: str,
+        data: Dict[str, Any],
+    ) -> None:
+        identifier = _identifier(user_id, conversation_id)
+        payload = {**data, "updatedAt": _utc_now_iso()}
+        try:
+            self._client.update(SWAP_SESSION_ENTITY, identifier, payload)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                self._handle_gateway_failure(exc)
+                raise
+            create_payload = {
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "tenantId": self._tenant_id(),
+                **payload,
+            }
+            try:
+                self._client.create(SWAP_SESSION_ENTITY, create_payload)
+            except PanoramaGatewayError as create_exc:
+                if create_exc.status_code == 409:
+                    return
+                if create_exc.status_code == 404:
+                    self._handle_gateway_failure(create_exc)
+                    raise
+                self._handle_gateway_failure(create_exc)
+                raise
+
+    def _create_history_entry(
+        self,
+        user_id: str,
+        conversation_id: str,
+        summary: Dict[str, Any],
+    ) -> None:
+        history_payload = {
+            "userId": user_id,
+            "conversationId": conversation_id,
+            "status": summary.get("status"),
+            "fromNetwork": summary.get("from_network"),
+            "fromToken": summary.get("from_token"),
+            "toNetwork": summary.get("to_network"),
+            "toToken": summary.get("to_token"),
+            "amount": _as_float(summary.get("amount")),
+            "errorMessage": summary.get("error"),
+            "recordedAt": _utc_now_iso(),
+            "tenantId": self._tenant_id(),
+        }
+        if self._logger.isEnabledFor(logging.DEBUG):
+            self._logger.debug(
+                "Persisting swap history for user=%s conversation=%s payload=%s",
+                user_id,
+                conversation_id,
+                history_payload,
+            )
+        try:
+            self._client.create(SWAP_HISTORY_ENTITY, history_payload)
+        except PanoramaGatewayError as exc:
+            if exc.status_code == 404:
+                self._handle_gateway_failure(exc)
+                raise
+            elif exc.status_code != 409:
+                self._handle_gateway_failure(exc)
+                raise
+
+    @staticmethod
+    def _session_payload(intent: Dict[str, Any], metadata: Dict[str, Any]) -> Dict[str, Any]:
+        missing = metadata.get("missing_fields") or []
+        if not isinstance(missing, list):
+            missing = list(missing)
+        return {
+            "status": metadata.get("status"),
+            "event": metadata.get("event"),
+            "intent": intent,
+            "missingFields": missing,
+            "nextField": metadata.get("next_field"),
+            "pendingQuestion": metadata.get("pending_question"),
+            "choices": metadata.get("choices"),
+            "errorMessage": metadata.get("error"),
+            "historyCursor": metadata.get("history_cursor") or 0,
+        }

src/agents/swap/tools.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 import time
 from contextlib import contextmanager
 from contextvars import ContextVar
@@ -19,6 +20,7 @@ from src.agents.swap.storage import SwapStateRepository
 
 # ---------- Helpers ----------
 _STORE = SwapStateRepository.instance()
+logger = logging.getLogger(__name__)
 
 
 def _format_decimal(value: Decimal) -> str:
@@ -325,6 +327,15 @@ def _store_swap_metadata(
     if history:
         meta["history"] = history
     metadata.set_swap_agent(meta, intent.user_id, intent.conversation_id)
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "Swap metadata stored for user=%s conversation=%s done=%s error=%s meta=%s",
+            intent.user_id,
+            intent.conversation_id,
+            done,
+            error,
+            meta,
+        )
     return meta
 
 
@@ -407,6 +418,19 @@ def update_swap_intent_tool(
     intent.conversation_id = resolved_conversation
 
     try:
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "update_swap_intent_tool input user=%s conversation=%s from_network=%s "
+                "from_token=%s to_network=%s to_token=%s amount=%s",
+                user_id,
+                conversation_id,
+                from_network,
+                from_token,
+                to_network,
+                to_token,
+                amount,
+            )
+
         if from_network is not None:
             canonical_from = _validate_network(from_network)
             if canonical_from != intent.from_network:
@@ -456,6 +480,13 @@ def update_swap_intent_tool(
     except ValueError as exc:
         message = str(exc)
         lowered = message.lower()
+        if logger.isEnabledFor(logging.INFO):
+            logger.info(
+                "Swap intent validation issue for user=%s conversation=%s: %s",
+                intent.user_id,
+                intent.conversation_id,
+                message,
+            )
         if "network" in lowered:
             return _response(
                 intent,
@@ -477,6 +508,13 @@ def update_swap_intent_tool(
                 error=message,
             )
         return _response(intent, "Please correct the input.", error=message)
+    except Exception as exc:
+        logger.exception(
+            "Unexpected error updating swap intent for user=%s conversation=%s",
+            intent.user_id,
+            intent.conversation_id,
+        )
+        return _response(intent, "Please try again with the swap details.", error=str(exc))
 
     if intent.from_network is None:
         return _response(

src/app.py

@@ -33,6 +33,7 @@ app.add_middleware(
 
 # Instantiate Supervisor agent (singleton LLM)
 supervisor = Supervisor(Config.get_llm())
+logger = logging.getLogger(__name__)
 
 class ChatRequest(BaseModel):
     message: ChatMessage
@@ -56,6 +57,7 @@ AVAILABLE_AGENTS = [
     {"name": "base", "human_readable_name": "Base Transaction Manager", "description": "Handle transactions on Base network."},
     {"name": "mor rewards", "human_readable_name": "MOR Rewards Tracker", "description": "Track MOR rewards and balances."},
     {"name": "mor claims", "human_readable_name": "MOR Claims Agent", "description": "Claim MOR tokens."},
+    {"name": "lending", "human_readable_name": "Lending Agent", "description": "Supply, borrow, repay, or withdraw assets."},
 ]
 
 # Default to a small, reasonable subset
@@ -73,6 +75,7 @@ AGENT_COMMANDS = [
     {"command": "dca", "name": "DCA Strategy Manager", "description": "Plan a dollar-cost averaging strategy."},
     {"command": "base", "name": "Base Transaction Manager", "description": "Send tokens and swap on Base."},
     {"command": "rewards", "name": "MOR Rewards Tracker", "description": "Check rewards balance and accrual."},
+    {"command": "lending", "name": "Lending Agent", "description": "Supply, borrow, repay, or withdraw assets."},
 ]
 
 # Agents endpoints expected by the frontend
@@ -110,11 +113,27 @@ def _map_agent_type(agent_name: str) -> str:
         "database_agent": "analysis",
         "search_agent": "realtime search",
         "swap_agent": "token swap",
+        "lending_agent": "lending",
         "supervisor": "supervisor",
     }
     return mapping.get(agent_name, "supervisor")
 
 
+def _sanitize_user_message_content(content: str | None) -> str | None:
+    """Strip wrapper prompts (e.g., 'User Message: ...') the frontend might send."""
+    if not content:
+        return content
+    text = content.strip()
+    marker = "user message:"
+    lowered = text.lower()
+    idx = lowered.rfind(marker)
+    if idx != -1:
+        candidate = text[idx + len(marker):].strip()
+        if candidate:
+            return candidate
+    return text
+
+
 def _resolve_identity(request: ChatRequest) -> tuple[str, str]:
     """Ensure each request has a stable user and conversation identifier."""
 
@@ -151,9 +170,36 @@ def get_conversations(request: Request):
 
 @app.post("/chat")
 def chat(request: ChatRequest):
-    print("request: ", request)
+    user_id: str | None = None
+    conversation_id: str | None = None
     try:
+        logger.debug("Received chat payload: %s", request.model_dump())
         user_id, conversation_id = _resolve_identity(request)
+        logger.debug(
+            "Resolved chat identity user=%s conversation=%s wallet=%s",
+            user_id,
+            conversation_id,
+            (request.wallet_address or "").strip() if request.wallet_address else None,
+        )
+
+        wallet = request.wallet_address.strip() if request.wallet_address else None
+        if wallet and wallet.lower() == "default":
+            wallet = None
+        display_name = None
+        if isinstance(request.message.metadata, dict):
+            display_name = request.message.metadata.get("display_name")
+
+        chat_manager_instance.ensure_session(
+            user_id,
+            conversation_id,
+            wallet_address=wallet,
+            display_name=display_name,
+        )
+
+        if request.message.role == "user":
+            clean_content = _sanitize_user_message_content(request.message.content)
+            if clean_content is not None:
+                request.message.content = clean_content
 
         # Add the user message to the conversation
         chat_manager_instance.add_message(
@@ -174,12 +220,16 @@ def chat(request: ChatRequest):
             conversation_id=conversation_id,
             user_id=user_id,
         )
+        logger.debug(
+            "Supervisor returned result for user=%s conversation=%s: %s",
+            user_id,
+            conversation_id,
+            result,
+        )
         
         # Add the agent's response to the conversation
         if result and isinstance(result, dict):
-            print("result: ", result)
             agent_name = result.get("agent", "supervisor")
-            print("agent_name: ", agent_name)
             agent_name = _map_agent_type(agent_name)
 
             # Build response metadata and enrich with coin info for crypto price queries
@@ -196,7 +246,19 @@ def chat(request: ChatRequest):
                 if swap_meta:
                     response_metadata.update(swap_meta)
                     swap_meta_snapshot = swap_meta
-            print("response_metadata: ", response_metadata)
+            elif agent_name == "lending":
+                lending_meta = metadata.get_lending_agent(
+                    user_id=user_id,
+                    conversation_id=conversation_id,
+                )
+                if lending_meta:
+                    response_metadata.update(lending_meta)
+            logger.debug(
+                "Response metadata for user=%s conversation=%s: %s",
+                user_id,
+                conversation_id,
+                response_metadata,
+            )
             
             # Create a ChatMessage from the supervisor response
             response_message = ChatMessage(
@@ -207,8 +269,8 @@ def chat(request: ChatRequest):
                 metadata=result.get("metadata", {}),
                 conversation_id=conversation_id,
                 user_id=user_id,
-                requires_action=True if agent_name == "token swap" else False,
-                action_type="swap" if agent_name == "token swap" else None
+                requires_action=True if agent_name in ["token swap", "lending"] else False,
+                action_type="swap" if agent_name == "token swap" else "lending" if agent_name == "lending" else None
             )
             
             # Add the response message to the conversation
@@ -248,10 +310,27 @@ def chat(request: ChatRequest):
                         user_id=user_id,
                         conversation_id=conversation_id,
                     )
+            if agent_name == "lending":
+                should_clear = False
+                if response_meta:
+                    status = response_meta.get("status") if isinstance(response_meta, dict) else None
+                    event = response_meta.get("event") if isinstance(response_meta, dict) else None
+                    should_clear = status == "ready" or event == "lending_intent_ready"
+                if should_clear:
+                    metadata.set_lending_agent(
+                        {},
+                        user_id=user_id,
+                        conversation_id=conversation_id,
+                    )
             return response_payload
         
         return {"response": "No response available", "agent": "supervisor"}
     except Exception as e:
+        logger.exception(
+            "Chat handler failed for user=%s conversation=%s",
+            user_id,
+            conversation_id,
+        )
         raise HTTPException(status_code=500, detail=str(e))
 
 # Include chat manager router

src/integrations/panorama_gateway/client.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import asdict
+import logging
+from typing import Any, Dict, Iterable, Optional
+
+import httpx
+import jwt
+
+from .config import PanoramaGatewaySettings, get_panorama_settings
+
+logger = logging.getLogger(__name__)
+
+
+class PanoramaGatewayError(RuntimeError):
+    """Raised when the Panorama gateway returns an error response."""
+
+    def __init__(self, message: str, status_code: int, payload: Any | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+
+
+def _encode_identifier(identifier: Any) -> str:
+    """Coerce identifiers into the colon-delimited format expected by the gateway."""
+
+    if isinstance(identifier, str):
+        return identifier
+    if isinstance(identifier, Iterable):
+        parts: Iterable[str] = (str(part) for part in identifier)
+        return ":".join(parts)
+    if isinstance(identifier, dict):
+        return ":".join(str(value) for value in identifier.values())
+    raise ValueError(f"Unsupported identifier type: {type(identifier)}")
+
+
+class PanoramaGatewayClient:
+    """HTTP client wrapper for Panorama's data gateway."""
+
+    def __init__(
+        self,
+        settings: PanoramaGatewaySettings | None = None,
+        *,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._settings = settings or get_panorama_settings()
+        self._client = client or httpx.Client(
+            base_url=self._settings.base_url,
+            timeout=self._settings.request_timeout,
+        )
+
+    def __enter__(self) -> "PanoramaGatewayClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    # ---- low-level helpers -------------------------------------------------
+    def _build_token(self) -> str:
+        now = int(time.time())
+        payload: Dict[str, Any] = {
+            "iat": now,
+            "exp": now + 300,
+            "service": self._settings.service_name,
+            "roles": self._settings.roles,
+            "tenant": self._settings.tenant_id,
+        }
+        if self._settings.jwt_audience:
+            payload["aud"] = self._settings.jwt_audience
+        if self._settings.jwt_issuer:
+            payload["iss"] = self._settings.jwt_issuer
+
+        return jwt.encode(payload, self._settings.jwt_secret, algorithm="HS256")
+
+    def _default_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._build_token()}",
+            "x-tenant-id": self._settings.tenant_id,
+            "Accept": "application/json",
+        }
+
+    @staticmethod
+    def _truncate_payload(payload: Any, limit: int = 512) -> Any:
+        if payload is None:
+            return None
+        try:
+            text = json.dumps(payload)
+        except (TypeError, ValueError):
+            text = str(payload)
+        if len(text) <= limit:
+            return payload
+        return text[:limit] + "...<truncated>"
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Dict[str, Any] | None = None,
+        json_body: Any | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        headers = self._default_headers()
+        if method.upper() in {"POST", "PATCH", "PUT", "DELETE"}:
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "Panorama %s %s params=%s body=%s",
+                method,
+                path,
+                params,
+                self._truncate_payload(json_body),
+            )
+
+        response = self._client.request(
+            method=method,
+            url=path,
+            headers=headers,
+            params=params,
+            json=json_body,
+        )
+
+        if response.status_code >= 400:
+            message = f"Gateway request failed ({response.status_code})"
+            try:
+                payload = response.json()
+            except ValueError:
+                payload = response.text
+            logger.warning(
+                "Panorama error %s %s status=%s payload=%s",
+                method,
+                path,
+                response.status_code,
+                payload,
+            )
+            raise PanoramaGatewayError(message, response.status_code, payload)
+
+        if response.status_code == 204:
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug("Panorama %s %s status=204 no-content", method, path)
+            return None
+
+        if response.headers.get("content-type", "").startswith("application/json"):
+            body = response.json()
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(
+                    "Panorama %s %s status=%s body=%s",
+                    method,
+                    path,
+                    response.status_code,
+                    self._truncate_payload(body),
+                )
+            return body
+
+        text = response.text
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                "Panorama %s %s status=%s body=%s",
+                method,
+                path,
+                response.status_code,
+                text[:512] + ("...<truncated>" if len(text) > 512 else ""),
+            )
+        return text
+
+    # ---- CRUD facades ------------------------------------------------------
+    def list(self, entity: str, query: Dict[str, Any] | None = None) -> Dict[str, Any]:
+        params = None
+        if query:
+            params = {}
+            for key, value in query.items():
+                if isinstance(value, (dict, list)):
+                    params[key] = json.dumps(value)
+                else:
+                    params[key] = value
+        return self._request("GET", f"/v1/{entity}", params=params)
+
+    def get(self, entity: str, identifier: Any) -> Any:
+        encoded_id = _encode_identifier(identifier)
+        return self._request("GET", f"/v1/{entity}/{encoded_id}")
+
+    def create(
+        self,
+        entity: str,
+        payload: Dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        return self._request(
+            "POST",
+            f"/v1/{entity}",
+            json_body=payload,
+            idempotency_key=idempotency_key,
+        )
+
+    def update(
+        self,
+        entity: str,
+        identifier: Any,
+        payload: Dict[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        encoded_id = _encode_identifier(identifier)
+        return self._request(
+            "PATCH",
+            f"/v1/{entity}/{encoded_id}",
+            json_body=payload,
+            idempotency_key=idempotency_key,
+        )
+
+    def delete(
+        self,
+        entity: str,
+        identifier: Any,
+        *,
+        idempotency_key: str | None = None,
+    ) -> None:
+        encoded_id = _encode_identifier(identifier)
+        self._request(
+            "DELETE",
+            f"/v1/{entity}/{encoded_id}",
+            idempotency_key=idempotency_key,
+        )
+
+    def transact(
+        self,
+        operations: Iterable[Dict[str, Any]],
+        *,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        payload = {"ops": list(operations)}
+        return self._request(
+            "POST",
+            "/v1/_transact",
+            json_body=payload,
+            idempotency_key=idempotency_key,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a serialisable snapshot of the current settings (useful for debugging)."""
+
+        return asdict(self._settings)

src/integrations/panorama_gateway/config.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import List, Optional
+
+
+def _split_roles(raw: str | None) -> List[str]:
+    if not raw:
+        return ["agent"]
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+@dataclass(slots=True)
+class PanoramaGatewaySettings:
+    """Runtime configuration for the Panorama data gateway client."""
+
+    base_url: str
+    jwt_secret: str
+    tenant_id: str = "tenant-agent"
+    service_name: str = "zico-agent"
+    roles: List[str] = field(default_factory=lambda: ["agent"])
+    jwt_audience: Optional[str] = None
+    jwt_issuer: Optional[str] = None
+    request_timeout: float = 10.0
+
+    @classmethod
+    def load(cls) -> "PanoramaGatewaySettings":
+        base_url = os.getenv("PANORAMA_GATEWAY_URL")
+        if not base_url:
+            raise ValueError("PANORAMA_GATEWAY_URL environment variable is required.")
+
+        secret = os.getenv("PANORAMA_GATEWAY_JWT_SECRET") or os.getenv("JWT_SECRET")
+        if not secret:
+            raise ValueError(
+                "Set PANORAMA_GATEWAY_JWT_SECRET or reuse JWT_SECRET for Panorama gateway auth."
+            )
+
+        return cls(
+            base_url=base_url.rstrip("/"),
+            jwt_secret=secret,
+            tenant_id=os.getenv("PANORAMA_GATEWAY_TENANT", "tenant-agent"),
+            service_name=os.getenv("PANORAMA_GATEWAY_SERVICE", "zico-agent"),
+            roles=_split_roles(os.getenv("PANORAMA_GATEWAY_ROLES", "agent")),
+            jwt_audience=os.getenv("PANORAMA_GATEWAY_JWT_AUDIENCE"),
+            jwt_issuer=os.getenv("PANORAMA_GATEWAY_JWT_ISSUER"),
+            request_timeout=float(os.getenv("PANORAMA_GATEWAY_TIMEOUT", "10")),
+        )
+
+
+@lru_cache(maxsize=1)
+def get_panorama_settings() -> PanoramaGatewaySettings:
+    """Memoized accessor so callers share a single settings instance."""
+
+    return PanoramaGatewaySettings.load()

src/service/chat_manager.py

@@ -1,125 +1,86 @@
+from __future__ import annotations
+
 import logging
-import time
+import uuid
 from typing import Dict, List, Optional
-from src.models.chatMessage import ChatMessage, ConversationState, AgentResponse
-from datetime import datetime
+
+from src.models.chatMessage import AgentResponse, ChatMessage
+from src.service.panorama_store import PanoramaStore
 
 logger = logging.getLogger(__name__)
 
 
 class ChatManager:
-    """
-    Manages chat conversations and message history.
-
-    This class provides functionality to:
-    - Create and manage multiple conversations identified by unique IDs
-    - Associate conversations with specific users
-    - Add/retrieve messages and responses within conversations
-    - Clear conversation history
-    - Get chat history in different formats
-    - Delete conversations
-
-    Each conversation starts with a default disclaimer message about the experimental nature
-    of the chatbot.
-
-    Attributes:
-        user_conversations (Dict[str, Dict[str, ConversationState]]): Dictionary mapping user IDs to their conversations
-        default_message (ChatMessage): Default disclaimer message added to new conversations
-
-    Example:
-        >>> chat_manager = ChatManager()
-        >>> chat_manager.add_message({"role": "user", "content": "Hello"}, "conv1", "user123")
-        >>> messages = chat_manager.get_messages("conv1", "user123")
-    """
-
-    def __init__(self) -> None:
-        self.user_conversations: Dict[str, Dict[str, ConversationState]] = {}
-        self.default_message = ChatMessage(
-            role="assistant",
-            content="""This highly experimental chatbot is not intended for making important decisions. Its
-                        responses are generated using AI models and may not always be accurate.
-                        By using this chatbot, you acknowledge that you use it at your own discretion
-                        and assume all risks associated with its limitations and potential errors.""",
-            metadata={},
-        )
-
-        # Backward compatibility - Initialize with default conversation for anonymous user
-        self._initialize_user("anonymous")
-        self.user_conversations["anonymous"]["default"] = ConversationState(
-            conversation_id="default",
-            user_id="anonymous",
-            messages=[self.default_message],
-            context={},
-            memory={},
-            agent_history=[],
-            current_agent=None,
-            last_message_id=None,
-            created_at=datetime.utcnow(),
-            updated_at=datetime.utcnow(),
-            is_active=True
-        )
-
-    def _get_conversation_id(self, conversation_id: Optional[str] = None) -> str:
-        """Helper method to get conversation ID, defaulting to 'default' if None provided"""
-        return conversation_id or "default"
-
-    def _get_user_id(self, user_id: Optional[str] = None) -> str:
-        """Helper method to get user ID, defaulting to 'anonymous' if None provided"""
-        return user_id or "anonymous"
-
-    def _initialize_user(self, user_id: str) -> None:
-        """Initialize conversations dictionary for a new user"""
-        if user_id not in self.user_conversations:
-            self.user_conversations[user_id] = {}
-            logger.info(f"Initialized conversations for user {user_id}")
-
-    def get_messages(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> List[Dict[str, str]]:
-        """
-        Get all messages for a specific conversation.
-
-        Args:
-            conversation_id (str, optional): Unique identifier for the conversation. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-
-        Returns:
-            List[Dict[str, str]]: List of messages as dictionaries
-        """
-        user_id = self._get_user_id(user_id)
-        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
-        return [msg.dict() for msg in conversation.messages]
-
-    def add_message(self, message: Dict[str, str], conversation_id: Optional[str] = None, user_id: Optional[str] = None):
-        """
-        Add a new message to a conversation.
-
-        Args:
-            message (Dict[str, str]): Message to add
-            conversation_id (str, optional): Conversation to add message to. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-        """
-        user_id = self._get_user_id(user_id)
-        conversation_id = self._get_conversation_id(conversation_id)
-        conversation = self._get_or_create_conversation(conversation_id, user_id)
+    """Facade that delegates chat persistence to the Panorama data gateway."""
+
+    def __init__(self, store: PanoramaStore | None = None) -> None:
+        self._store = store or PanoramaStore()
+
+    @staticmethod
+    def _resolve_ids(
+        conversation_id: Optional[str],
+        user_id: Optional[str],
+    ) -> tuple[str, str]:
+        return (conversation_id or "default", user_id or "anonymous")
+
+    # ---- Message access ---------------------------------------------------
+    def get_messages(
+        self,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> List[Dict[str, str]]:
+        conversation_id, user_id = self._resolve_ids(conversation_id, user_id)
+        self._store.ensure_conversation(user_id, conversation_id)
+        messages = self._store.list_messages(user_id, conversation_id)
+        return messages
+
+    def get_last_message(
+        self,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, str]:
+        messages = self.get_messages(conversation_id, user_id)
+        return messages[-1] if messages else {}
+
+    def get_chat_history(
+        self,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> str:
+        messages = self.get_messages(conversation_id, user_id)
+        return "\n".join(f"{msg.get('role')}: {msg.get('content')}" for msg in messages)
+
+    # ---- Mutations --------------------------------------------------------
+    def add_message(
+        self,
+        message: Dict[str, str],
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, str]:
+        conversation_id, user_id = self._resolve_ids(conversation_id, user_id)
+        self._store.ensure_user_and_conversation(user_id, conversation_id)
         chat_message = ChatMessage(**message)
+        if not chat_message.message_id:
+            chat_message.message_id = str(uuid.uuid4())
         chat_message.conversation_id = conversation_id
         chat_message.user_id = user_id
-        if "timestamp" not in message:
-            chat_message.timestamp = datetime.utcnow()
-        conversation.messages.append(chat_message)
-        logger.info(f"Added message to conversation {conversation_id} for user {user_id}: {chat_message.content}")
-
-    def add_response(self, response: Dict[str, str], agent_name: str, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
-        """
-        Add an agent's response to a conversation.
-
-        Args:
-            response (Dict[str, str]): Response content
-            agent_name (str): Name of the responding agent
-            conversation_id (str, optional): Conversation to add response to. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-        """
+        stored = self._store.add_message(user_id, conversation_id, chat_message)
+        logger.info(
+            "Persisted message for user=%s conversation=%s role=%s",
+            user_id,
+            conversation_id,
+            chat_message.role,
+        )
+        return stored
+
+    def add_response(
+        self,
+        response: Dict[str, str],
+        agent_name: str,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, str]:
         agent_response = AgentResponse(**response)
-        # You may need to implement to_chat_message if not present
         chat_message = ChatMessage(
             role="assistant",
             content=agent_response.content,
@@ -131,152 +92,82 @@ class ChatManager:
             next_agent=agent_response.next_agent,
             requires_followup=agent_response.requires_followup,
             status="completed" if agent_response.success else "failed",
-            error_message=agent_response.error_message
+            error_message=agent_response.error_message,
+        )
+        stored = self.add_message(
+            chat_message.dict(),
+            conversation_id=conversation_id,
+            user_id=user_id,
+        )
+        logger.info(
+            "Persisted agent response from %s for user=%s conversation=%s",
+            agent_name,
+            user_id,
+            conversation_id,
+        )
+        return stored
+
+    def clear_messages(
+        self,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> None:
+        conversation_id, user_id = self._resolve_ids(conversation_id, user_id)
+        self._store.ensure_conversation(user_id, conversation_id)
+        self._store.reset_conversation(user_id, conversation_id)
+        logger.info(
+            "Cleared messages for user=%s conversation=%s",
+            user_id,
+            conversation_id,
         )
-        self.add_message(chat_message.dict(), self._get_conversation_id(conversation_id), self._get_user_id(user_id))
-        logger.info(f"Added response from agent {agent_name} to conversation {conversation_id} for user {user_id}")
-
-    def clear_messages(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
-        """
-        Clear all messages in a conversation except the default message.
-
-        Args:
-            conversation_id (str, optional): Conversation to clear. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-        """
-        user_id = self._get_user_id(user_id)
-        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
-        conversation.messages = [self.default_message]  # Keep the initial message
-        logger.info(f"Cleared message history for conversation {conversation_id} for user {user_id}")
-
-    def get_last_message(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> Dict[str, str]:
-        """
-        Get the most recent message from a conversation.
-
-        Args:
-            conversation_id (str, optional): Conversation to get message from. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-
-        Returns:
-            Dict[str, str]: Last message or empty dict if no messages
-        """
-        user_id = self._get_user_id(user_id)
-        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
-        return conversation.messages[-1].dict() if conversation.messages else {}
-
-    def get_chat_history(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None) -> str:
-        """
-        Get formatted chat history for a conversation.
-
-        Args:
-            conversation_id (str, optional): Conversation to get history for. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-
-        Returns:
-            str: Formatted chat history as string
-        """
-        user_id = self._get_user_id(user_id)
-        conversation = self._get_or_create_conversation(self._get_conversation_id(conversation_id), user_id)
-        return "\n".join([f"{msg.role}: {msg.content}" for msg in conversation.messages])
-
-    def get_all_conversation_ids(self, user_id: Optional[str] = None) -> List[str]:
-        """
-        Get a list of all conversation IDs for a specific user.
-
-        Args:
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-
-        Returns:
-            List[str]: List of conversation IDs for the user
-        """
-        user_id = self._get_user_id(user_id)
-        self._initialize_user(user_id)
-        return list(self.user_conversations[user_id].keys())
-
-    def get_all_user_ids(self) -> List[str]:
-        """
-        Get a list of all user IDs.
-
-        Returns:
-            List[str]: List of user IDs
-        """
-        return list(self.user_conversations.keys())
-
-    def delete_conversation(self, conversation_id: Optional[str] = None, user_id: Optional[str] = None):
-        """
-        Delete a conversation by ID.
 
-        Args:
-            conversation_id (str, optional): ID of conversation to delete. Defaults to "default"
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-        """
-        user_id = self._get_user_id(user_id)
-        conversation_id = self._get_conversation_id(conversation_id)
-        self._initialize_user(user_id)
-        if conversation_id in self.user_conversations[user_id]:
-            del self.user_conversations[user_id][conversation_id]
-            logger.info(f"Deleted conversation {conversation_id} for user {user_id}")
+    def delete_conversation(
+        self,
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> None:
+        conversation_id, user_id = self._resolve_ids(conversation_id, user_id)
+        self._store.delete_conversation(user_id, conversation_id)
+        logger.info(
+            "Deleted conversation for user=%s conversation=%s",
+            user_id,
+            conversation_id,
+        )
 
     def create_conversation(self, user_id: Optional[str] = None) -> str:
-        """
-        Create a new conversation for a user.
-
-        Args:
-            user_id (str, optional): User identifier. Defaults to "anonymous"
-
-        Returns:
-            str: ID of the created conversation
-        """
-        user_id = self._get_user_id(user_id)
-        self._initialize_user(user_id)
-        conversation_id = f"conversation_{len(self.user_conversations[user_id])}"
-        while conversation_id in self.user_conversations[user_id]:
-            conversation_id = f"conversation_{len(self.user_conversations[user_id])}_{int(time.time())}"
-        self.user_conversations[user_id][conversation_id] = ConversationState(
-            conversation_id=conversation_id,
-            user_id=user_id,
-            messages=[self.default_message],
-            context={},
-            memory={},
-            agent_history=[],
-            current_agent=None,
-            last_message_id=None,
-            created_at=datetime.utcnow(),
-            updated_at=datetime.utcnow(),
-            is_active=True
+        user_id = (user_id or "anonymous")
+        conversation_id = f"conversation-{uuid.uuid4().hex[:8]}"
+        self._store.ensure_user_and_conversation(user_id, conversation_id)
+        logger.info(
+            "Created new conversation for user=%s conversation=%s",
+            user_id,
+            conversation_id,
         )
-        logger.info(f"Created new conversation {conversation_id} for user {user_id}")
         return conversation_id
 
-    def _get_or_create_conversation(self, conversation_id: str, user_id: str) -> ConversationState:
-        """
-        Get existing conversation or create new one if not exists.
-
-        Args:
-            conversation_id (str): Conversation ID to get/create
-            user_id (str): User identifier
+    # ---- Discovery helpers ------------------------------------------------
+    def get_all_conversation_ids(self, user_id: Optional[str] = None) -> List[str]:
+        user_id = (user_id or "anonymous")
+        return self._store.list_conversations(user_id)
 
-        Returns:
-            ConversationState: Retrieved or created conversation
-        """
-        self._initialize_user(user_id)
-        if conversation_id not in self.user_conversations[user_id]:
-            self.user_conversations[user_id][conversation_id] = ConversationState(
-                conversation_id=conversation_id,
-                user_id=user_id,
-                messages=[self.default_message],
-                context={},
-                memory={},
-                agent_history=[],
-                current_agent=None,
-                last_message_id=None,
-                created_at=datetime.utcnow(),
-                updated_at=datetime.utcnow(),
-                is_active=True
-            )
-            logger.info(f"Created new conversation {conversation_id} for user {user_id}")
-        return self.user_conversations[user_id][conversation_id]
+    def get_all_user_ids(self) -> List[str]:
+        return self._store.list_users()
+
+    def ensure_session(
+        self,
+        user_id: str,
+        conversation_id: str,
+        *,
+        wallet_address: Optional[str] = None,
+        display_name: Optional[str] = None,
+    ) -> None:
+        self._store.ensure_user_and_conversation(
+            user_id,
+            conversation_id,
+            wallet_address=wallet_address,
+            display_name=display_name,
+        )
 
 
-# Create an instance to act as a singleton store
+# Singleton-style accessor for the FastAPI routes
 chat_manager_instance = ChatManager()

src/service/panorama_store.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from src.models.chatMessage import ChatMessage
+
+from src.integrations.panorama_gateway import (
+    PanoramaGatewayClient,
+    PanoramaGatewayError,
+    PanoramaGatewaySettings,
+    get_panorama_settings,
+)
+
+
+DEFAULT_DISCLAIMER = (
+    "This highly experimental chatbot is not intended for making important decisions. "
+    "Its responses are generated using AI models and may not always be accurate. "
+    "By using this chatbot, you acknowledge that you use it at your own discretion "
+    "and assume all risks associated with its limitations and potential errors."
+)
+
+
+def _utc_now_iso() -> str:
+    """Return an RFC3339 timestamp with millisecond precision and Z suffix."""
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _normalize_datetime(value: Any | None) -> Optional[str]:
+    """Convert datetime-like inputs to gateway-friendly RFC3339 strings."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str):
+        if not value:
+            return None
+        try:
+            dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return value
+    else:
+        return value
+
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    else:
+        dt = dt.astimezone(timezone.utc)
+    return dt.isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _conversation_key(user_id: str, conversation_id: str) -> str:
+    return f"{user_id}:{conversation_id}"
+
+
+def _drop_none(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Remove keys with None values so the gateway never receives JSON null."""
+    return {key: value for key, value in data.items() if value is not None}
+
+
+class PanoramaStore:
+    """Bridges chat persistence to the Panorama data gateway."""
+
+    def __init__(
+        self,
+        *,
+        client: PanoramaGatewayClient | None = None,
+        settings: PanoramaGatewaySettings | None = None,
+    ) -> None:
+        self._settings = settings or get_panorama_settings()
+        self._client = client or PanoramaGatewayClient(self._settings)
+        self._logger = logging.getLogger(__name__)
+
+    # ---- user helpers -----------------------------------------------------
+    def ensure_user(
+        self,
+        user_id: str,
+        *,
+        wallet_address: Optional[str] = None,
+        display_name: Optional[str] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        try:
+            user = self._client.get("users", user_id)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                raise
+            user = None
+
+        if user:
+            # Update last seen without failing the request if the patch raises.
+            try:
+                payload: Dict[str, Any] = {"lastSeenAt": _utc_now_iso()}
+                if display_name:
+                    payload["displayName"] = display_name
+                if wallet_address:
+                    payload["walletAddress"] = wallet_address
+                if attributes:
+                    payload["attributes"] = attributes
+                self._client.update("users", user_id, payload)
+            except PanoramaGatewayError:
+                pass
+            return user
+
+        payload = _drop_none(
+            {
+                "userId": user_id,
+                "walletAddress": wallet_address,
+                "displayName": display_name,
+                "attributes": attributes or {},
+                "tenantId": self._settings.tenant_id,
+                "createdAt": _utc_now_iso(),
+                "lastSeenAt": _utc_now_iso(),
+            }
+        )
+        try:
+            return self._client.create("users", payload)
+        except PanoramaGatewayError as exc:
+            self._logger.error(
+                "Failed to create user %s via gateway: status=%s payload=%s request=%s",
+                user_id,
+                exc.status_code,
+                exc.payload,
+                payload,
+            )
+            raise
+
+    # ---- conversation helpers ---------------------------------------------
+    def ensure_conversation(
+        self,
+        user_id: str,
+        conversation_id: str,
+        *,
+        title: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        conv_key = _conversation_key(user_id, conversation_id)
+        try:
+            conversation = self._client.get("conversations", conv_key)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                raise
+            conversation = None
+
+        if conversation:
+            return conversation
+
+        payload = _drop_none(
+            {
+                "id": conv_key,
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "title": title,
+                "status": "active",
+                "messageCount": 0,
+                "tenantId": self._settings.tenant_id,
+                "contextState": {},
+                "memoryState": {},
+                "createdAt": _utc_now_iso(),
+                "updatedAt": _utc_now_iso(),
+            }
+        )
+        try:
+            conversation = self._client.create("conversations", payload)
+        except PanoramaGatewayError as exc:
+            self._logger.error(
+                "Failed to create conversation %s for user %s: status=%s payload=%s request=%s",
+                conversation_id,
+                user_id,
+                exc.status_code,
+                exc.payload,
+                payload,
+            )
+            raise
+        self._create_disclaimer_message(user_id, conversation_id)
+        return conversation
+
+    def list_conversations(self, user_id: str) -> List[str]:
+        result = self._client.list(
+            "conversations",
+            {
+                "where": {"userId": user_id},
+                "orderBy": {"updatedAt": "desc"},
+            },
+        )
+        data = result.get("data", []) if isinstance(result, dict) else []
+        return [item.get("conversationId") for item in data if item.get("conversationId")]
+
+    def list_users(self, limit: int = 1000) -> List[str]:
+        result = self._client.list(
+            "users",
+            {
+                "orderBy": {"createdAt": "desc"},
+                "take": limit,
+            },
+        )
+        data = result.get("data", []) if isinstance(result, dict) else []
+        return [item.get("userId") for item in data if item.get("userId")]
+
+    def delete_conversation(self, user_id: str, conversation_id: str) -> None:
+        messages = self.list_messages(user_id, conversation_id)
+        deletes: List[Dict[str, Any]] = [
+            {
+                "op": "delete",
+                "entity": "messages",
+                "args": {"id": message["messageId"]},
+            }
+            for message in messages
+            if message.get("messageId")
+        ]
+        if deletes:
+            self._client.transact(deletes)
+
+        conv_key = _conversation_key(user_id, conversation_id)
+        try:
+            self._client.delete("conversations", conv_key)
+        except PanoramaGatewayError as exc:
+            if exc.status_code != 404:
+                raise
+
+    def reset_conversation(self, user_id: str, conversation_id: str) -> None:
+        messages = self.list_messages(user_id, conversation_id)
+        deletes = [
+            {
+                "op": "delete",
+                "entity": "messages",
+                "args": {"id": message["messageId"]},
+            }
+            for message in messages
+            if message.get("messageId")
+        ]
+        if deletes:
+            self._client.transact(deletes)
+
+        conv_key = _conversation_key(user_id, conversation_id)
+        self._client.update(
+            "conversations",
+            conv_key,
+            {"messageCount": 0, "updatedAt": _utc_now_iso()},
+        )
+        self._create_disclaimer_message(user_id, conversation_id)
+
+    # ---- message helpers ---------------------------------------------------
+    def list_messages(self, user_id: str, conversation_id: str) -> List[Dict[str, Any]]:
+        result = self._client.list(
+            "messages",
+            {
+                "where": {"userId": user_id, "conversationId": conversation_id},
+                "orderBy": {"timestamp": "asc"},
+            },
+        )
+        if isinstance(result, dict):
+            return result.get("data", [])
+        return []
+
+    def add_message(
+        self,
+        user_id: str,
+        conversation_id: str,
+        message: ChatMessage,
+    ) -> Dict[str, Any]:
+        conversation = self.ensure_conversation(user_id, conversation_id)
+        message_dict = message.dict()
+        message_id = message_dict.get("message_id") or message_dict.get("messageId")
+        if not message_id:
+            message_id = str(uuid.uuid4())
+        timestamp = _normalize_datetime(message_dict.get("timestamp")) or _utc_now_iso()
+        message_payload = _drop_none(
+            {
+                "messageId": message_id,
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "role": message_dict.get("role"),
+                "content": message_dict.get("content"),
+                "agentName": message_dict.get("agent_name"),
+                "agentType": message_dict.get("agent_type"),
+                "requiresAction": message_dict.get("requires_action", False),
+                "actionType": message_dict.get("action_type"),
+                "metadata": message_dict.get("metadata") or {},
+                "status": message_dict.get("status"),
+                "errorMessage": message_dict.get("error_message"),
+                "toolCalls": message_dict.get("tool_calls"),
+                "toolResults": message_dict.get("tool_results"),
+                "nextAgent": message_dict.get("next_agent"),
+                "requiresFollowup": message_dict.get("requires_followup", False),
+                "timestamp": timestamp,
+                "tenantId": self._settings.tenant_id,
+            }
+        )
+
+        operations = [
+            {"op": "create", "entity": "messages", "args": {"data": message_payload}},
+            {
+                "op": "update",
+                "entity": "conversations",
+                "args": {
+                    "id": conversation["id"],
+                    "data": {
+                        "lastMessageId": message_payload["messageId"],
+                        "messageCount": (conversation.get("messageCount") or 0) + 1,
+                        "updatedAt": _utc_now_iso(),
+                    },
+                },
+            },
+        ]
+        self._client.transact(operations)
+
+        memory_payload = _drop_none(
+            {
+                "messageId": message_payload["messageId"],
+                "role": message_payload["role"],
+                "content": message_payload["content"],
+                "agentName": message_payload.get("agentName"),
+                "agentType": message_payload.get("agentType"),
+                "metadata": message_payload.get("metadata"),
+                "requiresAction": message_payload.get("requiresAction"),
+                "timestamp": message_payload.get("timestamp"),
+            }
+        )
+        try:
+            self.create_conversation_memory(
+                user_id,
+                conversation_id,
+                scope="conversation",
+                memory_type=message_payload["role"],
+                payload=memory_payload,
+            )
+        except PanoramaGatewayError:
+            # Memory writes should never block the main chat flow.
+            pass
+
+        return message_payload
+
+    def _create_disclaimer_message(self, user_id: str, conversation_id: str) -> None:
+        disclaimer = ChatMessage(
+            role="assistant",
+            content=DEFAULT_DISCLAIMER,
+            metadata={},
+            user_id=user_id,
+            conversation_id=conversation_id,
+        )
+        self.add_message(user_id, conversation_id, disclaimer)
+
+    # ---- conversation memory ----------------------------------------------
+    def create_conversation_memory(
+        self,
+        user_id: str,
+        conversation_id: Optional[str],
+        scope: str,
+        memory_type: str,
+        payload: Dict[str, Any],
+        *,
+        label: Optional[str] = None,
+        importance_score: Optional[float] = None,
+        expires_at: Optional[Any] = None,
+    ) -> Dict[str, Any]:
+        memory_payload = _drop_none(
+            {
+                "userId": user_id,
+                "conversationId": conversation_id,
+                "scope": scope,
+                "memoryType": memory_type,
+                "payload": payload,
+                "tenantId": self._settings.tenant_id,
+                "label": label,
+                "importanceScore": importance_score,
+                "expiresAt": _normalize_datetime(expires_at),
+                "createdAt": _utc_now_iso(),
+                "updatedAt": _utc_now_iso(),
+            }
+        )
+        return self._client.create("conversation-memories", memory_payload)
+
+    # ---- utility -----------------------------------------------------------
+    def ensure_user_and_conversation(
+        self,
+        user_id: str,
+        conversation_id: str,
+        *,
+        wallet_address: Optional[str] = None,
+        display_name: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        user = self.ensure_user(
+            user_id,
+            wallet_address=wallet_address,
+            display_name=display_name,
+        )
+        conversation = self.ensure_conversation(user_id, conversation_id)
+        return user, conversation