feat: complete phase 1 -- core framework with chat loop, agents, and React UI

Backend:
- FastAPI WebSocket /ws endpoint with streaming via LangGraph astream
- LangGraph Supervisor connecting 3 mock agents (order_lookup, order_actions, fallback)
- YAML Agent Registry with Pydantic validation and immutable configs
- PostgresSaver checkpoint persistence via langgraph-checkpoint-postgres
- Session TTL with 30-min sliding window and interrupt extension
- LLM provider abstraction (Anthropic/OpenAI/Google)
- Token usage + cost tracking callback handler
- Input validation: message size cap, thread_id format, content length
- Security: no hardcoded defaults, startup API key validation, no input reflection

Frontend:
- React 19 + TypeScript + Vite chat UI
- WebSocket hook with reconnect + exponential backoff
- Streaming token display with agent attribution
- Interrupt approval/reject UI for write operations
- Collapsible tool call viewer

Testing:
- 87 unit tests, 87% coverage (exceeds 80% requirement)
- Ruff lint + format clean

Infrastructure:
- Docker Compose (PostgreSQL 16 + backend)
- pyproject.toml with full dependency management

backend/app/agents/__init__.py

@@ -0,0 +1,30 @@
+"""Agent tools registry -- maps tool name strings to actual tool functions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.tools import BaseTool
+
+from app.agents.fallback import fallback_respond
+from app.agents.order_actions import cancel_order
+from app.agents.order_lookup import get_order_status, get_tracking_info
+
+_TOOL_MAP: dict[str, BaseTool] = {
+    "get_order_status": get_order_status,
+    "get_tracking_info": get_tracking_info,
+    "cancel_order": cancel_order,
+    "fallback_respond": fallback_respond,
+}
+
+
+def get_tools_by_names(tool_names: list[str]) -> list[BaseTool]:
+    """Resolve tool name strings from YAML config to actual tool objects."""
+    tools = []
+    for name in tool_names:
+        if name not in _TOOL_MAP:
+            available = ", ".join(sorted(_TOOL_MAP.keys()))
+            raise ValueError(f"Unknown tool '{name}'. Available tools: {available}")
+        tools.append(_TOOL_MAP[name])
+    return tools

backend/app/agents/fallback.py

@@ -0,0 +1,18 @@
+"""Fallback agent tools -- handles unmatched intents."""
+
+from __future__ import annotations
+
+from langchain_core.tools import tool
+
+
+@tool
+def fallback_respond(query: str) -> str:
+    """Provide a helpful response when the user's intent doesn't match a specific agent."""
+    return (
+        "I'm here to help with order inquiries and actions. "
+        "Here's what I can do:\n"
+        "- Check order status (e.g., 'What is the status of order 1042?')\n"
+        "- Get tracking information (e.g., 'Track order 1042')\n"
+        "- Cancel an order (e.g., 'Cancel order 1042')\n\n"
+        "Could you please rephrase your request?"
+    )

backend/app/agents/order_actions.py

@@ -0,0 +1,37 @@
+"""Order action tools -- write operations requiring human approval."""
+
+from __future__ import annotations
+
+from langchain_core.tools import tool
+from langgraph.types import interrupt
+
+
+@tool
+def cancel_order(order_id: str) -> dict:
+    """Cancel an order. Requires human approval before execution."""
+    response = interrupt(
+        {
+            "action": "cancel_order",
+            "order_id": order_id,
+            "message": f"Please confirm: cancel order {order_id}?",
+        }
+    )
+
+    if isinstance(response, bool):
+        approved = response
+    elif isinstance(response, dict):
+        approved = response.get("approved", False)
+    else:
+        approved = bool(response)
+
+    if approved:
+        return {
+            "status": "cancelled",
+            "order_id": order_id,
+            "message": f"Order {order_id} has been successfully cancelled.",
+        }
+    return {
+        "status": "kept",
+        "order_id": order_id,
+        "message": f"Order {order_id} cancellation was declined. The order remains active.",
+    }

backend/app/agents/order_lookup.py

@@ -0,0 +1,68 @@
+"""Order lookup tools -- read-only operations."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+
+from langchain_core.tools import tool
+
+MOCK_ORDERS: MappingProxyType[str, dict] = MappingProxyType(
+    {
+        "1042": {
+            "order_id": "1042",
+            "status": "shipped",
+            "items": ["Wireless Headphones", "USB-C Cable"],
+            "total": 89.99,
+            "placed_at": "2026-03-25",
+        },
+        "1043": {
+            "order_id": "1043",
+            "status": "processing",
+            "items": ["Laptop Stand"],
+            "total": 49.99,
+            "placed_at": "2026-03-28",
+        },
+        "1044": {
+            "order_id": "1044",
+            "status": "delivered",
+            "items": ["Mechanical Keyboard", "Mouse Pad"],
+            "total": 159.99,
+            "placed_at": "2026-03-20",
+        },
+    }
+)
+
+MOCK_TRACKING: MappingProxyType[str, dict] = MappingProxyType(
+    {
+        "1042": {
+            "order_id": "1042",
+            "carrier": "FedEx",
+            "tracking_number": "FX-9876543210",
+            "estimated_delivery": "2026-04-01",
+            "current_location": "Distribution Center, Chicago IL",
+        },
+        "1044": {
+            "order_id": "1044",
+            "carrier": "UPS",
+            "tracking_number": "1Z-5678901234",
+            "estimated_delivery": "2026-03-22",
+            "current_location": "Delivered",
+        },
+    }
+)
+
+
+@tool
+def get_order_status(order_id: str) -> dict:
+    """Look up the current status of an order by order ID."""
+    if order_id in MOCK_ORDERS:
+        return dict(MOCK_ORDERS[order_id])
+    return {"error": f"Order {order_id} not found", "order_id": order_id}
+
+
+@tool
+def get_tracking_info(order_id: str) -> dict:
+    """Get shipping and tracking information for an order."""
+    if order_id in MOCK_TRACKING:
+        return dict(MOCK_TRACKING[order_id])
+    return {"error": f"No tracking information for order {order_id}", "order_id": order_id}