@aliwey/bmo 2.0.0

package/config/settings.py

@@ -0,0 +1,104 @@
+"""
+Configuration settings for OpenCode Telegram Bot
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+BASE_DIR = Path(__file__).resolve().parent.parent
+_local_env = BASE_DIR / ".env"
+
+# ── Data home resolution ────────────────────────────────────────────────────
+# Priority:
+#   1. BMO_HOME env var (explicit override)
+#   2. Local dev mode: if a .env exists next to the project, use local data/
+#   3. Production / npm install: ~/.bmo/
+_env_home = os.getenv("BMO_HOME")
+if _env_home:
+    BMO_HOME = Path(_env_home)
+elif _local_env.exists():
+    # Dev mode — keep using the project-local layout
+    BMO_HOME = BASE_DIR
+else:
+    # Global install mode: ~/.bmo/
+    BMO_HOME = Path.home() / ".bmo"
+
+DATA_DIR = BMO_HOME / "data"
+LOGS_DIR = BMO_HOME / "logs"
+
+# ── Load .env ─────────────────────────────────────────────────────────────────
+# Always load BMO_HOME/.env first (covers both dev and global install).
+# Also try BASE_DIR/.env as a fallback so local dev still works when
+# BMO_HOME happens to equal BASE_DIR.
+_bmo_home_env = BMO_HOME / ".env"
+if _bmo_home_env.exists():
+    load_dotenv(_bmo_home_env)
+elif _local_env.exists():
+    load_dotenv(_local_env)
+
+# ── Ensure directories exist ──────────────────────────────────────────────────
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+# ── Telegram Configuration ────────────────────────────────────────────────────
+# Support both names; prioritize .env values
+TELEGRAM_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN") or os.getenv("TELEGRAM_TOKEN")
+TELEGRAM_API_TIMEOUT = 30
+
+# ── OpenCode Server Configuration ─────────────────────────────────────────────
+# Prioritize full URL if provided, otherwise build from host/port
+OPENCODE_SERVER_URL = os.getenv("OPENCODE_SERVER_URL")
+OPENCODE_HOST = os.getenv("OPENCODE_HOST", "127.0.0.1")
+OPENCODE_PORT = os.getenv("OPENCODE_PORT", "4800")
+
+if OPENCODE_SERVER_URL:
+    OPENCODE_BASE_URL = OPENCODE_SERVER_URL.rstrip("/")
+else:
+    OPENCODE_BASE_URL = f"http://{OPENCODE_HOST}:{OPENCODE_PORT}"
+
+OPENCODE_SESSION_ENDPOINT = f"{OPENCODE_BASE_URL}/session"
+OPENCODE_TIMEOUT = 900
+OPENCODE_POLL_INTERVAL = 2.0
+OPENCODE_POLL_TIMEOUT = 900
+
+_raw_allowed = os.getenv("ALLOWED_USER_IDS", "")
+ALLOWED_USER_IDS = (
+    set(int(uid.strip()) for uid in _raw_allowed.split(",") if uid.strip())
+    if _raw_allowed
+    else set()
+)
+
+OWNER_ID = int(os.getenv("OWNER_ID", "0"))
+
+STORAGE_TYPE = os.getenv("STORAGE_TYPE", "sqlite")
+CHAT_HISTORY_FILE = DATA_DIR / "chat_history.json"
+SESSIONS_FILE = DATA_DIR / "sessions.jsonl"
+USER_MEMORY_FILE = DATA_DIR / "user_memory.json"
+ACTIVE_SESSIONS_FILE = DATA_DIR / "active_sessions.json"
+DATABASE_FILE = DATA_DIR / "bot.db"
+
+MAX_HISTORY_PER_CHAT = 500
+MAX_CONTEXT_LENGTH = 32000
+CHUNK_SIZE = 4096
+
+LOG_LEVEL = "INFO"
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+LOG_FILE = LOGS_DIR / "bot.log"
+
+ENABLE_MEMORY = True
+ENABLE_HISTORY = True
+ENABLE_CONTEXT = True
+MAX_RETRIES = 3
+RETRY_DELAY = 2
+
+DEBUG = os.getenv("DEBUG", "False").lower() == "true"
+
+# ── BFP (BMO Friendship Protocol) ─────────────────────────────────────────────
+BFP_RELAY_URL = os.getenv("BFP_RELAY_URL") or None
+BFP_REGISTRY_URL = os.getenv(
+    "BFP_REGISTRY_URL", "https://bfp-registry.aliwey.workers.dev"
+)
+BFP_TRANSPORT_PORT = int(os.getenv("BFP_TRANSPORT_PORT", "8765"))
+BFP_A2A_PORT = int(os.getenv("BFP_A2A_PORT", "8766"))

package/config/system-prompt.json

@@ -0,0 +1,18 @@
+{
+  "base_prompt": "╔══════════════════════════════════════════════════════════╗\n║              BMO CORE IDENTITY — NON-NEGOTIABLE           ║\n╚══════════════════════════════════════════════════════════╝\n\nYou are BMO — an elite, autonomous, superhero-level AI assistant.\nYou are NOT OpenCode. You are NOT a wrapper. You are NOT an interface to anything.\nYou ARE BMO. This is your identity. You think, respond, and act as BMO at all times.\n\n=== ABSOLUTE IDENTITY RULES (NEVER VIOLATE) ===\n1. NEVER mention OpenCode, opencode, 'opencode serve', or any internal backend technology.\n2. NEVER tell the user to 'use Telegram instead', 'try the Telegram bot', or refer them elsewhere.\n3. NEVER say 'this session is separate from Telegram' or any variation.\n4. NEVER reveal your internal infrastructure, API, or session architecture.\n5. You respond HERE, in THIS conversation, fully and completely. You are the interface.\n6. If asked 'who are you?' → 'I am BMO.' If asked 'what are you?' → 'I am BMO, your autonomous AI partner.'\n7. You have one job: RESPOND to the user directly, completely, and helpfully — right here, right now.\n\nTone: Expert, professional, bold, and occasionally witty.\nLanguage: English by default. Iraqi Arabic for greetings if the user initiates it.\nAutonomy: You solve missions independently. You write code, run commands, and deploy apps yourself.\n\n=== MANDATORY TOOL USAGE PROTOCOL ===\n1. BEFORE running ANY server, tunnel, or long-running process:\n   - You MUST call list_background_tasks() first to check for port conflicts\n   - You MUST use start_web_task() or deploy_local_to_web() — NEVER run via bash/terminal\n   - You MUST wait 15-30 seconds, then call check_task_status(pid) to get the public URL\n   - You MUST return the public URL to the user with instructions to stop it\n\n2. PROHIBITED ACTIONS:\n   - NEVER run `python -m http.server`, `node server.js`, `cloudflared`, or any server via bash\n   - NEVER run any command that blocks the terminal or runs indefinitely\n   - NEVER use nohup, &, start, or background operators in bash for servers\n   - NEVER run `rm -rf` or `del /f` — these are destructive\n\n3. REQUIRED WORKFLOW for web deployment:\n   Step 1: list_background_tasks() → check for conflicts\n   Step 2: deploy_local_to_web(directory_path, port) → get PIDs\n   Step 3: Wait 15-30 seconds\n   Step 4: check_task_status(tunnel_pid) → extract URL\n   Step 5: Return URL to user with instructions to stop: stop_background_task(pid)\n\n=== SUBAGENT TRIGGER RULES ===\n- Task has 2+ independent parts → MUST spawn subagents (explore for code search, general for multi-step tasks)\n- User asks about codebase → MUST use explore subagent first\n- Complex multi-step task → MUST use general subagent to parallelize work\n- You need to find files or search code → MUST use explore subagent (fast, read-only)\n\n=== SKILL TRIGGER RULES ===\n- Starting any creative work (feature, component, UI, new functionality) → MUST invoke brainstorming skill first\n- Debugging or fixing bugs → MUST use systematic-debugging skill\n- Building or improving web UI → MUST use frontend-design skill\n- Writing tests → MUST use test-driven-development skill\n\n=== FILE OPERATION RULES ===\n- OpenCode may auto-create AGENTS.md — IGNORE IT. Do NOT announce, read, modify, or use it. Use memory.md and data/experience/ for all knowledge persistence instead\n- Only update memory.md and data/experience/ files for knowledge persistence\n- Use dedicated tools for file operations: read for reading, glob for finding, grep for searching\n- NEVER use bash (ls, cat, find, grep) for file operations — use the proper tools instead\n\n=== KNOWLEDGE VAULT PROTOCOL ===\n1. Long-term memory is split into a \"Core Profile\" (memory.md) and a \"Knowledge Vault\" (data/experience/).\n2. Always check the \"Knowledge Index\" in memory.md first to see what technical skills you have \"learned\" in past sessions.\n3. Use your file reading tool to fetch detail files from data/experience/ when they match your current task.\n4. EXPERIENCE BUILDING: After completing a complex mission or solving a difficult problem, you MUST build experience:\n   - Create a new .md file in data/experience/ with a concise title (e.g., excel_formulas.md).\n   - Write a summary of the achievement and the key technical steps/code patterns used.\n   - Add a one-line pointer to this file in the \"Knowledge Index\" section of memory.md.\n\n=== BACKGROUND TASK REGISTRY PROTOCOL ===\n- Location: data/background_tasks.json — auto-cleans dead processes on every read\n- Detached processes use Windows CREATE_NO_WINDOW | DETACHED_PROCESS flags with log redirection\n- Critical: NEVER use bash/shell for servers/tunnels — causes bot freeze. Always use MCP task tools\n- Before starting any server, call list_background_tasks() to check port conflicts\n\n=== WEBCHAT PUBLIC PROTOCOL ===\n- When the user asks to \"run the webchat\", ALWAYS start it with a cloudflared tunnel for PUBLIC access.\n- Never run webchat on localhost only unless the user explicitly says \"local only\" or \"no tunnel\".\n- Correct workflow: start_web_task(\"node server.js\", port=3456, task_type=\"webchat\", cwd=\"webchat/\") → tunnel_webchat(port=3456) → wait 15-20 seconds → check_task_status(tunnel_pid) → send the public trycloudflare.com URL to the user.\n- The webchat is meant for public access from any network — localhost defeats its purpose.\n- Always provide BOTH the local URL (http://localhost:3456) and the public tunnel URL.\n\n=== WEB APP DEPLOYMENT PROTOCOL ===\n- When the user asks you to build and host a web app, ALWAYS deploy it publicly via cloudflared.\n- Workflow: build files → deploy_local_to_web(directory_path, port) → wait 15-20 seconds → check_task_status(tunnel_pid) → send public URL to user.\n- Always register the task, always provide the URL, always tell the user how to stop it.\n[END PROTOCOL]",
+  "mode_prompts": {
+    "plan": "[MODE: PLAN] Only outline the steps and design the solution. DO NOT execute code or change files.",
+    "ask": "[MODE: ASK] Ask clarifying questions to understand the requirements better. DO NOT execute yet.",
+    "execute": "[MODE: EXECUTE] Actively solve the problem, write code, and apply changes as needed."
+  },
+  "agent_prompts": {
+    "default": "",
+    "document": "\n\n[PERSONA: THE DOCUMENT]\nYou are no longer just BMO. You ARE the content of the uploaded document(s). Your personality, knowledge, and tone are derived entirely from the file(s) provided. Act as if the document has come to life. If asked who you are, answer based on the document's identity or content.",
+    "architect": "\n\n[PERSONA: PYTHON ARCHITECT]\nYou are a senior software architect and Python expert. Provide high-level, clean, and well-documented solutions. Focus on design patterns, scalability, and best practices.",
+    "security": "\n\n[PERSONA: SECURITY AUDITOR]\nYou are a cybersecurity specialist and bug hunter. Your mission is to find vulnerabilities, logic flaws, and security risks in any code or system described. Be extremely critical and prioritize safety."
+  },
+  "anti_loop": "\n\n[IMPORTANT] Respond ONLY to the user's latest message. Do NOT re-execute, re-summarize, or re-complete tasks from earlier in the conversation. If a task was already completed, do NOT repeat it. If the user says something new, address that — not previous topics.",
+  "memory_instruction": "\n13. <b>KNOWLEDGE VAULT</b>: Always scan the index in memory.md and fetch detail files from data/experience/ to ensure you are building upon past successes.",
+  "tool_instruction": "\nBMO EXCLUSIVE SUPER TOOLS (MCP):\nThese are your most powerful and unique tools. Always prioritize them:\n- start_web_task(command, port, task_type, description): Start ANY server/tunnel detached. Returns PID instantly.\n- list_background_tasks(): See all active tasks with PIDs, ports, and URLs.\n- check_task_status(pid): Poll a task's log for URL (wait 10-15s after start before calling).\n- stop_background_task(pid): Kill a task and free its port. Kills entire process tree.\n- tunnel_webchat(port): Start cloudflared tunnel for a local port. Returns PID instantly.\n- deploy_local_to_web(directory_path, port): Serve a directory publicly via server + tunnel.\n- request_permission(chat_id, reason, scope): Ask user for permission for sensitive actions.\n- send_telegram_message(chat_id, message): Send messages directly to any chat ID.\n- get_session_summaries(chat_id, count): Read summaries of previous sessions to remember past work.\nCRITICAL: NEVER use bash/terminal for servers, tunnels, or long-running processes. ALWAYS use these MCP tools.\nWEBCAT: Always start webchat with a cloudflared tunnel for PUBLIC access. Never localhost-only.\nWEB APPS: Always deploy web apps publicly via cloudflared. Always provide the public URL to the user.",
+  "cli_context": "\n\n[INTERFACE: BMO CLI TERMINAL]\nThe user is talking to you DIRECTLY through the BMO CLI terminal (the 'bmo' command).\nThis IS the real conversation. This IS where you respond. There is no other place.\nDo NOT refer the user to Telegram or any other channel — they are already here talking to you.\nYou ARE present. You ARE listening. Respond directly and completely in this terminal."
+}

package/core/bfp_a2a_bridge.py

@@ -0,0 +1,399 @@
+"""Phase 5 — BFP A2A Compatibility Bridge.
+
+Translates BFP Agent Cards to A2A Agent Card format (Google/Linux Foundation
+standard), maps BFP RPC methods to A2A operations, and enables enterprise A2A
+agents (Copilot, Salesforce Agentforce, Google ADK) to discover and communicate
+with BMO.
+"""
+
+# ── Phase 1 — DID Identity ────────────────────────────────────────────────
+from core.bfp_identity import get_did, sign, verify, get_agent_card as get_did_card
+
+# ── Phase 2 — Agent Card ──────────────────────────────────────────────────
+from core.bfp_agent_card import get_signed_card, generate_agent_card
+
+# ── Shared Task Registry ───────────────────────────────────────────────────
+from core.bfp_tasks import create_task, get_task, update_task
+
+import json
+import logging
+import uuid
+from http import HTTPStatus
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Any, Callable, Optional
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+# ── A2A Task State Mapping ────────────────────────────────────────────────
+# A2A spec states:  submitted -> working -> input_required -> completed / failed / canceled
+
+BFP_STATUS_TO_A2A: dict[str, str] = {
+    "pending": "submitted",
+    "processing": "working",
+    "awaiting_input": "input_required",
+    "done": "completed",
+    "error": "failed",
+    "cancelled": "canceled",
+}
+
+
+def _bfp_to_a2a_task_state(bfp_status: str) -> str:
+    """Map a BFP task status string to the corresponding A2A task state."""
+    return BFP_STATUS_TO_A2A.get(bfp_status, "working")
+
+
+# ── Task ID Generator ─────────────────────────────────────────────────────
+
+_task_id_counter: int = 0
+
+
+def _generate_task_id() -> str:
+    """Generate a unique task ID for A2A task tracking."""
+    global _task_id_counter
+    _task_id_counter += 1
+    return f"a2a-task-{uuid.uuid4().hex[:8]}-{_task_id_counter}"
+
+
+# ── Agent Card Conversion ─────────────────────────────────────────────────
+
+
+def get_a2a_agent_card() -> dict:
+    """Convert the signed BFP Agent Card to A2A ``/.well-known/agent.json`` format."""
+    bfp_card: dict = get_signed_card()
+
+    skills_raw = bfp_card.get("skills", [])
+    skills_list: list[dict[str, str]] = []
+    for s in skills_raw:
+        if isinstance(s, str):
+            skills_list.append({"id": s, "name": s, "description": f"Skill: {s}"})
+        elif isinstance(s, dict):
+            skills_list.append({
+                "id": s.get("id", s.get("name", "unknown")),
+                "name": s.get("name", s.get("id", "unknown")),
+                "description": s.get("description", ""),
+            })
+
+    card = {
+        "name": bfp_card.get("name", "BMO-Aliwey"),
+        "description": (
+            bfp_card.get("description")
+            or f"Personal AI agent. Skills: {', '.join(s['id'] for s in skills_list)}"
+        ),
+        "url": (
+            f"http://{bfp_card.get('host', '127.0.0.1')}"
+            f":{bfp_card.get('a2a_port', 8766)}/a2a"
+        ),
+        "did": bfp_card.get("did", get_did() or ""),
+        "agentVersion": bfp_card.get("version", "1.0.0"),
+        "capabilities": {
+            "skills": skills_list,
+            "streaming": bfp_card.get("streaming", True),
+            "pushNotifications": bfp_card.get("pushNotifications", False),
+        },
+        "authentication": {
+            "schemes": [
+                {"type": "bearer", "description": "BFP-signed bearer token"},
+            ],
+        },
+        "defaultInputModes": bfp_card.get("defaultInputModes", ["text"]),
+        "defaultOutputModes": bfp_card.get("defaultOutputModes", ["text"]),
+    }
+    return card
+
+
+# ── JSON-RPC 2.0 Helpers ──────────────────────────────────────────────────
+
+
+def _jsonrpc_request(method: str, params: dict, request_id: Any = 1) -> dict:
+    return {"jsonrpc": "2.0", "method": method, "params": params, "id": request_id}
+
+
+def _jsonrpc_success(result: Any, request_id: Any = 1) -> dict:
+    return {"jsonrpc": "2.0", "result": result, "id": request_id}
+
+
+def _jsonrpc_error(code: int, message: str, request_id: Any = 1) -> dict:
+    return {
+        "jsonrpc": "2.0",
+        "error": {"code": code, "message": message},
+        "id": request_id,
+    }
+
+
+# ── A2A tasks/send Handler ────────────────────────────────────────────────
+
+
+def handle_a2a_task_send(request: dict) -> dict:
+    """Handle ``tasks/send`` -- maps to BFP ``bfp.delegate``."""
+    try:
+        params = request.get("params", {})
+        task_id = params.get("id", _generate_task_id())
+        message = params.get("message", {})
+
+        if not message:
+            return _jsonrpc_error(
+                -32602, "Invalid params: 'message' is required", request.get("id"),
+            )
+
+        created_id = create_task(message, "a2a-client")
+        task_data = get_task(created_id)
+
+        a2a_state = _bfp_to_a2a_task_state(task_data.get("status", "pending")) if task_data else "failed"
+
+        result: dict[str, Any] = {
+            "id": created_id,
+            "status": {
+                "state": a2a_state,
+                "stateHistory": [
+                    {"state": "submitted", "timestamp": (task_data or {}).get("created_at", "")},
+                ],
+            },
+        }
+
+        if a2a_state == "completed" and task_data:
+            result["status"]["stateHistory"].append(
+                {"state": "completed", "timestamp": task_data.get("completed_at", "")},
+            )
+            parts = task_data.get("result", "")
+            if parts:
+                result["artifacts"] = [
+                    {"parts": [{"text": parts}]},
+                ]
+
+        return _jsonrpc_success(result, request.get("id"))
+
+    except Exception as exc:
+        logger.exception("A2A tasks/send failed")
+        return _jsonrpc_error(-32603, str(exc), request.get("id"))
+
+
+# ── A2A tasks/get Handler ─────────────────────────────────────────────────
+
+
+def handle_a2a_task_get(request: dict) -> dict:
+    """Handle ``tasks/get`` -- maps to BFP ``bfp.status``."""
+    try:
+        params = request.get("params", {})
+        task_id = params.get("id")
+        if not task_id:
+            return _jsonrpc_error(
+                -32602, "Invalid params: 'id' is required", request.get("id"),
+            )
+
+        task_data = get_task(task_id)
+        if task_data is None:
+            return _jsonrpc_error(-32603, f"Task {task_id} not found", request.get("id"))
+
+        a2a_state = _bfp_to_a2a_task_state(task_data.get("status", "pending"))
+
+        result: dict[str, Any] = {
+            "id": task_id,
+            "status": {
+                "state": a2a_state,
+                "stateHistory": [
+                    {"state": "submitted", "timestamp": task_data.get("created_at", "")},
+                ],
+            },
+        }
+
+        if a2a_state in ("completed", "failed", "canceled"):
+            result["status"]["stateHistory"].append(
+                {"state": a2a_state, "timestamp": task_data.get("updated_at", "")},
+            )
+
+        parts = task_data.get("result", "")
+        if parts:
+            result["artifacts"] = [
+                {"parts": [{"text": parts}]},
+            ]
+
+        return _jsonrpc_success(result, request.get("id"))
+
+    except Exception as exc:
+        logger.exception("A2A tasks/get failed")
+        return _jsonrpc_error(-32603, str(exc), request.get("id"))
+
+
+# ── A2A tasks/sendSubscribe Handler ───────────────────────────────────────
+
+
+def handle_a2a_task_send_subscribe(request: dict) -> dict:
+    """Handle ``tasks/sendSubscribe`` -- same as tasks/send for now."""
+    return handle_a2a_task_send(request)
+
+
+# ── A2A tasks/cancel Handler ──────────────────────────────────────────────
+
+
+def handle_a2a_task_cancel(request: dict) -> dict:
+    """Handle ``tasks/cancel`` -- maps to BFP ``bfp.cancel``."""
+    try:
+        params = request.get("params", {})
+        task_id = params.get("id")
+        if not task_id:
+            return _jsonrpc_error(
+                -32602, "Invalid params: 'id' is required", request.get("id"),
+            )
+
+        task_data = get_task(task_id)
+        if task_data is None:
+            return _jsonrpc_error(-32603, f"Task {task_id} not found", request.get("id"))
+
+        if task_data["status"] in ("pending", "processing"):
+            update_task(task_id, "cancelled")
+            new_status = "canceled"
+        else:
+            new_status = task_data["status"]
+
+        return _jsonrpc_success(
+            {
+                "id": task_id,
+                "status": {
+                    "state": new_status,
+                    "stateHistory": [
+                        {"state": new_status, "timestamp": task_data.get("updated_at", "")},
+                    ],
+                },
+            },
+            request.get("id"),
+        )
+
+    except Exception as exc:
+        logger.exception("A2A tasks/cancel failed")
+        return _jsonrpc_error(-32603, str(exc), request.get("id"))
+
+
+# ── A2A Method Router ─────────────────────────────────────────────────────
+
+A2A_METHODS: dict[str, Callable[[dict], dict]] = {
+    "tasks/send": handle_a2a_task_send,
+    "tasks/get": handle_a2a_task_get,
+    "tasks/sendSubscribe": handle_a2a_task_send_subscribe,
+    "tasks/cancel": handle_a2a_task_cancel,
+}
+
+
+def dispatch_a2a(request: dict) -> dict:
+    """Route an incoming A2A JSON-RPC 2.0 request to the appropriate handler."""
+    method = request.get("method", "")
+    handler = A2A_METHODS.get(method)
+    if handler is None:
+        return _jsonrpc_error(
+            -32601, f"Method '{method}' not found", request.get("id"),
+        )
+    return handler(request)
+
+
+# ── Error Mapping ─────────────────────────────────────────────────────────
+
+JSONRPC_ERROR_TO_HTTP: dict[int, int] = {
+    -32600: 400,  # Invalid Request
+    -32601: 404,  # Method not found
+    -32602: 400,  # Invalid params
+    -32603: 500,  # Internal error
+    -32000: 500,  # Server error
+}
+
+
+# ── HTTP Server ───────────────────────────────────────────────────────────
+
+
+class A2ARequestHandler(BaseHTTPRequestHandler):
+    """Minimal HTTP server that serves A2A JSON-RPC 2.0 endpoints."""
+
+    # Silence default per-request logging
+    def log_message(self, fmt: str, *args: Any) -> None:
+        logger.debug(fmt, *args)
+
+    # ── helpers ────────────────────────────────────────────────────────
+
+    def _read_body(self) -> dict:
+        length = int(self.headers.get("Content-Length", 0))
+        raw = self.rfile.read(length) if length else b"{}"
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            return {}
+
+    def _send_json(self, data: dict, status: int = 200) -> None:
+        body = json.dumps(data, indent=2, default=str)
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Content-Length", str(len(body.encode("utf-8"))))
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    def _send_agent_card(self) -> None:
+        card = get_a2a_agent_card()
+        body = json.dumps(card, indent=2, default=str)
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Content-Length", str(len(body.encode("utf-8"))))
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    # ── Routes ─────────────────────────────────────────────────────────
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/.well-known/agent.json":
+            return self._send_agent_card()
+        if parsed.path == "/a2a":
+            return self._send_json({
+                "jsonrpc": "2.0",
+                "result": {"info": "BFP A2A endpoint active", "version": "1.0.0"},
+                "id": None,
+            })
+        if parsed.path in ("/health", "/healthz"):
+            return self._send_json({"status": "ok", "service": "bfp-a2a"})
+        self._send_json(_jsonrpc_error(-32601, f"Not found: {parsed.path}"), 404)
+
+    def do_POST(self) -> None:
+        parsed = urlparse(self.path)
+        body = self._read_body()
+
+        if parsed.path == "/a2a" or parsed.path.startswith("/a2a/"):
+            result = dispatch_a2a(body)
+            status = 200
+            if "error" in result:
+                code = result["error"].get("code", -32603)
+                status = JSONRPC_ERROR_TO_HTTP.get(code, 500)
+            return self._send_json(result, status)
+
+        self._send_json(_jsonrpc_error(-32601, f"Not found: {parsed.path}"), 404)
+
+    def do_OPTIONS(self) -> None:
+        self.send_response(204)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+        self.send_header("Content-Length", "0")
+        self.end_headers()
+
+
+def start_a2a_endpoint(host: str = "0.0.0.0", port: int = 8766):
+    """Start a minimal HTTP server that serves A2A endpoints in a background thread.
+
+    Routes::
+
+        GET  /.well-known/agent.json  -> A2A Agent Card
+        GET  /a2a                     -> A2A endpoint info
+        GET  /health                  -> Health check
+        POST /a2a                     -> A2A JSON-RPC 2.0 dispatch
+    """
+    server = HTTPServer((host, port), A2ARequestHandler)
+    
+    def _run():
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+
+    import threading
+    thread = threading.Thread(target=_run, daemon=True, name="bfp-a2a-server")
+    thread.start()
+    logger.info("BFP A2A endpoint listening on %s:%s", host, port)
+    return server