Initial modernized KAPO runtime upload

.env

@@ -0,0 +1,31 @@
+BRAIN_AUTO_NGROK=0
+BRAIN_AUTO_PUBLISH_URL_ON_STARTUP=0
+BRAIN_LANGUAGES=ar,en
+BRAIN_PLATFORM_NAME=ai_coder_main
+BRAIN_PROVIDER=huggingface
+BRAIN_REUSE_PUBLIC_URL_ON_RESTART=0
+BRAIN_ROLES=coding,planner,fallback
+BRAIN_TEMPLATE=hf-space-cpu
+BRAIN_TUNNEL_PROVIDER=none
+FIREBASE_ENABLED=0
+FIREBASE_NAMESPACE=kapo
+FIREBASE_PROJECT_ID=citadel4travels
+GOOGLE_DRIVE_BOOTSTRAP_URL=https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG
+HF_ACCELERATOR=cpu
+HF_SPACE_DOCKER=1
+KAGGLE_AUTO_BOOTSTRAP=0
+KAPO_BOOTSTRAP_URL=https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG
+KAPO_COMPUTE_PROFILE=cpu
+KAPO_HF_INFERENCE_API=1
+KAPO_HF_TRANSFORMERS_RUNTIME=0
+KAPO_LAZY_EMBED_STARTUP=1
+KAPO_LAZY_MODEL_STARTUP=1
+KAPO_PATCH_BUNDLE_URL=https://drive.google.com/uc?export=download&id=16rIe05GZihhAz7ba8E-WibKaJKbh9eu1
+KAPO_PATCH_MANIFEST_URL=https://drive.google.com/uc?export=download&id=1jLuPMCA3hp9qstZZtpBNzTK0XOmLrV8b
+KAPO_REMOTE_ENV_PASSWORD_B64=cENvSnljQ0Z6RUN2azRpcUFLVUdQLW9BbVBoTEtNOFE
+KAPO_REMOTE_ENV_URL_B64=aHR0cHM6Ly9kcml2ZS5nb29nbGUuY29tL3VjP2V4cG9ydD1kb3dubG9hZCZpZD0xdjlZRDlNYlBKNUdYNk9WanVHM3hOR05xLWJfQlJfTGY
+KAPO_SHARED_STATE_BACKEND=google_drive
+MODEL_PROFILE_ID=hf-coder-qwen25-coder-7b-instruct
+MODEL_REPO=Qwen/Qwen2.5-Coder-1.5B-Instruct
+REMOTE_BRAIN_ONLY=1
+SPACE_PUBLIC_URL=https://MrA7A1-AiCoder.hf.space

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONUTF8=1
+COPY requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+RUN mkdir -p /data/kapo_runtime/current /data/kapo_runtime/overlay
+COPY brain_server /app/brain_server
+COPY shared /app/shared
+COPY .env /app/.env
+COPY kapo.env /app/kapo.env
+COPY bootstrap_space_runtime.py /app/bootstrap_space_runtime.py
+CMD ["python", "/app/bootstrap_space_runtime.py"]

README.md

@@ -1,10 +1,21 @@
----
-title: AiCoderClean
-emoji: 👀
-colorFrom: pink
-colorTo: green
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: ai_coder_main
+emoji: 🤖
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+---
+
+# ai_coder_main
+
+Generated Hugging Face deployment package from KAPO Control Center.
+
+Model profile: hf-coder-qwen25-coder-7b-instruct
+Model repo: Qwen/Qwen2.5-Coder-1.5B-Instruct
+Model file: not set
+Roles: coding, planner, fallback
+Languages: ar, en
+
+This is a Docker-oriented Hugging Face Space package.
+Push the extracted contents to a Docker Space repository, configure secrets/env vars, then set the resulting Base URL in the platform registry.

bootstrap_space_runtime.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+DEFAULT_ENV = {
+  "BRAIN_AUTO_NGROK": "0",
+  "BRAIN_AUTO_PUBLISH_URL_ON_STARTUP": "0",
+  "BRAIN_LANGUAGES": "ar,en",
+  "BRAIN_PLATFORM_NAME": "ai_coder_main",
+  "BRAIN_PROVIDER": "huggingface",
+  "BRAIN_REUSE_PUBLIC_URL_ON_RESTART": "0",
+  "BRAIN_ROLES": "coding,planner,fallback",
+  "BRAIN_TEMPLATE": "hf-space-cpu",
+  "BRAIN_TUNNEL_PROVIDER": "none",
+  "FIREBASE_ENABLED": "0",
+  "FIREBASE_NAMESPACE": "kapo",
+  "FIREBASE_PROJECT_ID": "citadel4travels",
+  "GOOGLE_DRIVE_BOOTSTRAP_URL": "https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG",
+  "HF_ACCELERATOR": "cpu",
+  "HF_SPACE_DOCKER": "1",
+  "KAGGLE_AUTO_BOOTSTRAP": "0",
+  "KAPO_BOOTSTRAP_URL": "https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG",
+  "KAPO_COMPUTE_PROFILE": "cpu",
+  "KAPO_HF_INFERENCE_API": "1",
+  "KAPO_HF_TRANSFORMERS_RUNTIME": "0",
+  "KAPO_LAZY_EMBED_STARTUP": "1",
+  "KAPO_LAZY_MODEL_STARTUP": "1",
+  "KAPO_PATCH_BUNDLE_URL": "https://drive.google.com/uc?export=download&id=16rIe05GZihhAz7ba8E-WibKaJKbh9eu1",
+  "KAPO_PATCH_MANIFEST_URL": "https://drive.google.com/uc?export=download&id=1jLuPMCA3hp9qstZZtpBNzTK0XOmLrV8b",
+  "KAPO_REMOTE_ENV_PASSWORD_B64": "cENvSnljQ0Z6RUN2azRpcUFLVUdQLW9BbVBoTEtNOFE",
+  "KAPO_REMOTE_ENV_URL_B64": "aHR0cHM6Ly9kcml2ZS5nb29nbGUuY29tL3VjP2V4cG9ydD1kb3dubG9hZCZpZD0xdjlZRDlNYlBKNUdYNk9WanVHM3hOR05xLWJfQlJfTGY",
+  "KAPO_SHARED_STATE_BACKEND": "google_drive",
+  "MODEL_PROFILE_ID": "hf-coder-qwen25-coder-7b-instruct",
+  "MODEL_REPO": "Qwen/Qwen2.5-Coder-1.5B-Instruct",
+  "REMOTE_BRAIN_ONLY": "1",
+  "SPACE_PUBLIC_URL": "https://MrA7A1-AiCoder.hf.space"
+}
+
+
+def _copy_tree(source: Path, target: Path) -> None:
+    if target.exists():
+        shutil.rmtree(target, ignore_errors=True)
+    shutil.copytree(
+        source,
+        target,
+        ignore=shutil.ignore_patterns('__pycache__', '*.pyc', '.git', '.venv'),
+    )
+
+
+def _merge_overlay(overlay_root: Path, runtime_root: Path) -> None:
+    if not overlay_root.exists():
+        return
+    for path in sorted(overlay_root.rglob('*')):
+        rel = path.relative_to(overlay_root)
+        dst = runtime_root / rel
+        if path.is_dir():
+            dst.mkdir(parents=True, exist_ok=True)
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, dst)
+
+
+def main() -> None:
+    source_root = Path(os.getenv('KAPO_SPACE_SOURCE_ROOT', '/app')).resolve()
+    default_root = Path('/data/kapo_runtime/current') if Path('/data').exists() else Path('/tmp/kapo_runtime/current')
+    runtime_root = Path(os.getenv('KAPO_RUNTIME_ROOT', str(default_root))).resolve()
+    overlay_root = Path(os.getenv('KAPO_OVERLAY_ROOT', str(runtime_root.parent / 'overlay'))).resolve()
+    runtime_pkg = runtime_root / 'brain_server'
+    source_pkg = source_root / 'brain_server'
+    for key, value in DEFAULT_ENV.items():
+        os.environ.setdefault(str(key), str(value))
+    space_host = str(os.getenv('SPACE_HOST', '')).strip().rstrip('/')
+    space_id = str(os.getenv('SPACE_ID', '')).strip()
+    public_url = ''
+    if space_host:
+        public_url = space_host if space_host.startswith('http://') or space_host.startswith('https://') else f'https://{space_host}'
+    elif space_id and '/' in space_id:
+        public_url = 'https://' + space_id.replace('/', '-').lower() + '.hf.space'
+    if public_url:
+        os.environ['BRAIN_PUBLIC_URL'] = public_url.rstrip('/')
+    runtime_root.mkdir(parents=True, exist_ok=True)
+    overlay_root.mkdir(parents=True, exist_ok=True)
+    if not runtime_pkg.exists():
+        _copy_tree(source_pkg, runtime_pkg)
+    _merge_overlay(overlay_root, runtime_root)
+    os.environ['KAPO_RUNTIME_ROOT'] = str(runtime_root)
+    os.environ['KAPO_SYNC_ROOT'] = str(runtime_root)
+    os.environ['KAPO_OVERLAY_ROOT'] = str(overlay_root)
+    port = str(os.getenv('PORT', '7860') or '7860')
+    os.execvp(
+        sys.executable,
+        [
+            sys.executable,
+            '-m',
+            'uvicorn',
+            'api.main:app',
+            '--host',
+            '0.0.0.0',
+            '--port',
+            port,
+            '--app-dir',
+            str(runtime_pkg),
+        ],
+    )
+
+
+if __name__ == '__main__':
+    main()

brain_server/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

brain_server/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# تثبيت الأدوات الأساسية
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# نسخ requirements
+COPY requirements.txt /app/requirements.txt
+
+# تثبيت المكتبات
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+# نسخ المشروع بحيث يعمل المساران: /app/api و /app/brain_server/api
+COPY . /app/brain_server/
+COPY . /app/
+
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 7860
+
+ENV PYTHONPATH=/app:/app/brain_server
+
+CMD ["uvicorn", "api.main:app", "--host", "0.0.0.0", "--port", "7860"]

brain_server/README.md

@@ -0,0 +1,10 @@
+---
+title: Ai Brain
+emoji: 🚀
+colorFrom: pink
+colorTo: red
+sdk: docker
+pinned: false
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

brain_server/agents/__init__.py

@@ -0,0 +1 @@
+"""???? ???????."""

brain_server/agents/auto_heal_agent.py

@@ -0,0 +1,22 @@
+"""Auto-Heal Agent: ????? ?????? ??????? ???????."""
+import logging
+from typing import Dict, Any
+from api.deps import get_logger
+
+logger = get_logger("kapo.agent.auto_heal")
+
+ERROR_MAP = {
+    "ModuleNotFoundError": "pip install <package>",
+    "command not found": "apt-get install <package>",
+    "SyntaxError": "???? ????? ????? ????? ????????",
+    "Permission denied": "???? ?? ??????? ?????? ?? ?????? ???? ?????",
+}
+
+
+class AutoHealAgent:
+    def suggest(self, error_text: str, step: Dict[str, Any]) -> Dict[str, Any]:
+        """?????? ??? ????? ???? ??? ?????."""
+        for key, fix in ERROR_MAP.items():
+            if key in error_text:
+                return {"error": error_text, "suggested_fix": fix, "step": step}
+        return {"error": error_text, "suggested_fix": "???? ?? ????? ??????"}

brain_server/agents/memory_agent.py

@@ -0,0 +1,51 @@
+"""Memory Agent: ?????? ?????? ???????."""
+import logging
+from typing import Any, Dict
+from memory.short_term import ShortTermMemory
+from memory.episodic_db import EpisodicDB
+from memory.knowledge_vector import KnowledgeVectorStore
+from api.deps import get_logger, is_remote_brain_only
+from agents.supervisor_agent import AgentOS
+
+logger = get_logger("kapo.agent.memory")
+
+
+class MemoryAgent:
+    def __init__(self):
+        self.remote_only = is_remote_brain_only()
+        self.short = ShortTermMemory()
+        self.episodic = None if self.remote_only else EpisodicDB()
+        self.knowledge = None if self.remote_only else KnowledgeVectorStore()
+        self.agent_os = None if self.remote_only else AgentOS()
+
+    def write_short_term(self, key: str, value: Dict[str, Any]) -> None:
+        if self.remote_only:
+            return
+        self.short.set(key, value)
+
+    def read_short_term(self, key: str) -> Dict[str, Any] | None:
+        if self.remote_only:
+            return None
+        return self.short.get(key)
+
+    def store_experience(self, payload: Dict[str, Any]) -> None:
+        if self.remote_only or self.episodic is None:
+            return
+        self.episodic.insert_experience(
+            task=payload.get("task", ""),
+            plan=payload.get("plan", {}),
+            tools_used=payload.get("tools_used", {}),
+            result=payload.get("result", {}),
+            success=1 if payload.get("success") else 0,
+        )
+
+    def query_knowledge(self, text: str, top_k: int = 3):
+        if self.remote_only or self.knowledge is None:
+            return []
+        return self.knowledge.query(text, top_k=top_k)
+
+    def run_agent_os(self):
+        """????? ???? ??????? ?????? ??????."""
+        if self.remote_only or self.agent_os is None:
+            return {"skipped": True, "reason": "REMOTE_BRAIN_ONLY"}
+        return self.agent_os.run()

brain_server/agents/planner_agent.py

@@ -0,0 +1,88 @@
+"""Planner agent that builds structured execution-friendly plans."""
+
+from typing import Any
+
+from api.deps import get_logger
+
+logger = get_logger("kapo.agent.planner")
+
+
+def _contains_any(text: str, terms: tuple[str, ...]) -> bool:
+    lowered = text.lower()
+    return any(term in lowered for term in terms)
+
+
+class PlannerAgent:
+    def _base_step(self, step_id: str, action: str, user_input: str, tool_hint: str, role: str) -> dict[str, Any]:
+        return {
+            "id": step_id,
+            "action": action,
+            "input": user_input,
+            "tool_hint": tool_hint,
+            "role": role,
+        }
+
+    def run(self, user_input: str, context: dict[str, Any]) -> list[dict[str, Any]]:
+        try:
+            text = (user_input or "").strip()
+            if not text:
+                return [self._base_step("step-1", "respond", "Empty request", "python", "chat")]
+
+            context = context or {}
+            steps: list[dict[str, Any]] = [
+                {
+                    **self._base_step("step-1", "analyze", text, "python", "planner"),
+                    "context_keys": sorted(context.keys()),
+                }
+            ]
+
+            research_terms = ("search", "research", "browse", "look up", "find out", "ابحث", "بحث", "دور", "فتش")
+            coding_terms = (
+                "build", "fix", "debug", "refactor", "implement", "generate", "write code", "api", "fastapi", "python",
+                "react", "repo", "project", "اصلح", "نفذ", "شغل", "عدل", "ابني", "برمجة", "كود", "مشروع",
+            )
+            planning_terms = ("plan", "roadmap", "architecture", "analyze", "design", "structure", "خطة", "بنية", "معمارية", "حلل")
+            explain_terms = ("explain", "describe", "summarize", "اشرح", "وضح", "لخص", "عرفني")
+
+            is_research = _contains_any(text, research_terms)
+            is_coding = _contains_any(text, coding_terms)
+            is_planning = _contains_any(text, planning_terms)
+            is_explainer = _contains_any(text, explain_terms)
+
+            if is_research:
+                steps.extend(
+                    [
+                        self._base_step("step-2", "research", text, "web", "chat"),
+                        self._base_step("step-3", "synthesize", "Summarize and cite the most relevant findings", "python", "supervisor"),
+                    ]
+                )
+            elif is_coding:
+                steps.extend(
+                    [
+                        self._base_step("step-2", "collect_requirements", "Inspect impacted files, dependencies, and constraints", "python", "planner"),
+                        self._base_step("step-3", "execute", text, "python", "coding"),
+                        self._base_step("step-4", "verify", "Run validation checks and inspect resulting output", "python", "coding"),
+                        self._base_step("step-5", "summarize", "Summarize what changed, risks, and verification status", "python", "supervisor"),
+                    ]
+                )
+            elif is_planning:
+                steps.extend(
+                    [
+                        self._base_step("step-2", "decompose", "Break the request into phases, dependencies, and risks", "python", "planner"),
+                        self._base_step("step-3", "respond", "Provide a structured implementation plan", "python", "supervisor"),
+                    ]
+                )
+            elif is_explainer:
+                steps.extend(
+                    [
+                        self._base_step("step-2", "collect_context", "Gather the minimum relevant context for explanation", "python", "chat"),
+                        self._base_step("step-3", "respond", "Explain the topic clearly and directly", "python", "supervisor"),
+                    ]
+                )
+            else:
+                steps.append(self._base_step("step-2", "respond", text, "python", "chat"))
+
+            return steps
+        except Exception as exc:
+            logger.exception("Planner failed")
+            return [{"id": "step-err", "action": "error", "input": str(exc), "tool_hint": "python", "role": "fallback"}]

brain_server/agents/reasoning_agent.py

@@ -0,0 +1,20 @@
+"""Reasoning Agent: ???? ????? ????? ?????."""
+import logging
+from typing import List, Dict, Any
+from api.deps import get_logger
+
+logger = get_logger("kapo.agent.reasoning")
+
+
+class ReasoningAgent:
+    def run(self, user_input: str, plan: List[Dict[str, Any]]) -> Dict[str, Any]:
+        try:
+            logger.info("Reasoning", extra={"component": "reasoning"})
+            return {
+                "summary": "?? ????? ????? ??? ????? ????? ??????.",
+                "steps_count": len(plan),
+                "input": user_input,
+            }
+        except Exception as exc:
+            logger.exception("Reasoning failed")
+            return {"error": str(exc)}

brain_server/agents/supervisor_agent.py

@@ -0,0 +1,38 @@
+"""Supervisor Agent: ????? ??????? ????? ??????."""
+import logging
+from typing import Any, Dict, List
+from api.deps import get_logger
+from memory.episodic_db import EpisodicDB
+
+logger = get_logger("kapo.agent.supervisor")
+
+
+class SupervisorAgent:
+    def review(self, results: List[Dict[str, Any]]) -> Dict[str, Any]:
+        try:
+            success = all(r.get("exit_code", 0) == 0 for r in results if isinstance(r, dict))
+            return {"success": success, "results_count": len(results)}
+        except Exception as exc:
+            logger.exception("Supervisor failed")
+            return {"success": False, "error": str(exc)}
+
+
+class AgentOS:
+    """Self-Improving loop reading episodic DB and proposing prompt updates."""
+
+    def run(self) -> Dict[str, Any]:
+        try:
+            db = EpisodicDB()
+            recent = db.list_recent(limit=20)
+            success_rate = 0
+            if recent:
+                success_rate = sum(1 for r in recent if r.get("success")) / len(recent)
+            proposal = {
+                "summary": f"Recent success rate: {success_rate:.2f}",
+                "prompt_update": "?????? ????? ????? Planner ??? ?????? ??????.",
+                "sandbox_test": "Run simulated plan execution in sandbox before promotion.",
+            }
+            return proposal
+        except Exception as exc:
+            logger.exception("AgentOS failed")
+            return {"error": str(exc)}

brain_server/agents/tool_selector_agent.py

@@ -0,0 +1,103 @@
+"""Tool selector for remote execution steps."""
+import sqlite3
+from typing import Any
+
+from api.deps import get_logger, load_config
+
+logger = get_logger("kapo.agent.tool_selector")
+
+
+class ToolSelectorAgent:
+    def __init__(self):
+        self.cfg = load_config()
+
+    def _load_catalog(self) -> list[dict[str, Any]]:
+        tools_db = self.cfg.get("TOOLS_DB_PATH")
+        if not tools_db or not str(tools_db).endswith(".db"):
+            return []
+
+        try:
+            conn = sqlite3.connect(str(tools_db))
+            cur = conn.cursor()
+            cur.execute(
+                """
+                SELECT tool_name, install_command, path, description, installed
+                FROM tools
+                """
+            )
+            rows = cur.fetchall()
+            conn.close()
+        except sqlite3.OperationalError:
+            return []
+        except Exception:
+            logger.exception("Tool catalog load failed")
+            return []
+
+        return [
+            {
+                "tool_name": row[0],
+                "install_command": row[1],
+                "path": row[2],
+                "description": row[3] or "",
+                "installed": bool(row[4]),
+            }
+            for row in rows
+        ]
+
+    def _step_text(self, step: dict[str, Any]) -> str:
+        for key in ("input", "description", "title", "summary", "task", "prompt"):
+            value = str(step.get(key, "")).strip()
+            if value:
+                return value
+        return ""
+
+    def _fallback_tool(self, tool_hint: str) -> dict[str, Any]:
+        name = f"fallback_{tool_hint or 'command'}"
+        return {
+            "tool_name": name,
+            "description": "Synthetic fallback tool selected by ToolSelectorAgent",
+            "path": tool_hint or "",
+            "installed": True,
+        }
+
+    def _fallback_command(self, step: dict[str, Any], tool_hint: str = "") -> str:
+        action = str(step.get("action", "")).strip().lower()
+        step_input = self._step_text(step)
+        explicit_command = str(step.get("command", "")).strip()
+        if explicit_command:
+            return explicit_command
+        if action == "research":
+            return f"echo Research task queued: {step_input}".strip()
+        if action in {"verify", "summarize", "respond", "synthesize"}:
+            if step_input:
+                return f"python -c \"print({step_input!r})\""
+            return "echo Verification requested"
+        if action in {"execute", "collect_requirements", "analyze", "decompose", "collect_context"}:
+            return f"python -c \"print({step_input!r})\"" if step_input else "python -c \"print('step received')\""
+        if tool_hint in {"python", "py"} or not tool_hint:
+            return f"python -c \"print({step_input!r})\"" if step_input else "python -c \"print('step received')\""
+        if step_input:
+            return f"echo {step_input}"
+        return "echo Step received"
+
+    def select_tool(self, step: dict[str, Any]) -> dict[str, Any]:
+        action = str(step.get("action", "")).strip().lower()
+        tool_hint = str(step.get("tool_hint", "")).strip().lower()
+        step_input = self._step_text(step).lower()
+        catalog = self._load_catalog()
+
+        for tool in catalog:
+            haystack = " ".join([tool["tool_name"], tool["description"], tool["path"] or ""]).lower()
+            if tool_hint and tool_hint in haystack:
+                return {"command": tool["path"] or tool["tool_name"], "files": {}, "env": {}, "tool": tool}
+            if action and action in haystack:
+                return {"command": tool["path"] or tool["tool_name"], "files": {}, "env": {}, "tool": tool}
+            if step_input and any(token in haystack for token in step_input.split()[:4]):
+                return {"command": tool["path"] or tool["tool_name"], "files": {}, "env": {}, "tool": tool}
+
+        return {
+            "command": self._fallback_command(step, tool_hint=tool_hint),
+            "files": step.get("files", {}),
+            "env": step.get("env", {}),
+            "tool": self._fallback_tool(tool_hint or "python"),
+        }

brain_server/api/__init__.py

@@ -0,0 +1 @@
+"""API package."""

brain_server/api/deps.py

@@ -0,0 +1,159 @@
+"""Common dependency utilities for Brain API."""
+import logging
+import logging.config
+import os
+import re
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+from shared.remote_env import load_remote_env_if_configured
+
+CONFIG_CACHE: dict[str, Any] | None = None
+_LOGGING_READY = False
+PLACEHOLDER_RE = re.compile(r"^\$\{[A-Z0-9_]+\}$")
+
+
+def _load_env_stack() -> None:
+    candidates = [
+        ".env",
+        "kapo.env",
+        ".env.runtime",
+    ]
+    for candidate in candidates:
+        try:
+            load_dotenv(candidate, override=True)
+        except Exception:
+            continue
+
+
+def _normalize_config_paths(cfg: dict[str, Any]) -> dict[str, Any]:
+    if os.name != "nt":
+        return cfg
+
+    root = os.getcwd()
+    normalized = dict(cfg)
+    path_keys = {
+        "DB_PATH",
+        "TOOLS_DB_PATH",
+        "FAISS_INDEX_PATH",
+        "BRAIN_LOG_PATH",
+        "EXEC_LOG_PATH",
+        "LOCAL_DATA_DIR",
+    }
+    for key in path_keys:
+        value = normalized.get(key)
+        if not isinstance(value, str) or not value:
+            continue
+        if value.startswith("/data"):
+            normalized[key] = os.path.join(root, "data", value[len("/data"):].lstrip("/\\"))
+        elif value.startswith("/models"):
+            normalized[key] = os.path.join(root, "models", value[len("/models"):].lstrip("/\\"))
+    return normalized
+
+
+def _strip_unresolved_placeholders(value):
+    if isinstance(value, dict):
+        return {key: _strip_unresolved_placeholders(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_strip_unresolved_placeholders(item) for item in value]
+    if isinstance(value, str) and PLACEHOLDER_RE.match(value.strip()):
+        return ""
+    return value
+
+
+def load_config() -> dict:
+    global CONFIG_CACHE
+    if CONFIG_CACHE is not None:
+        return CONFIG_CACHE
+
+    _load_env_stack()
+    load_remote_env_if_configured(override=True, logger_name="kapo.brain.remote_env")
+    config_path = os.path.join(os.path.dirname(__file__), "..", "config", "config.yaml")
+    with open(config_path, "r", encoding="utf-8") as handle:
+        raw = handle.read()
+
+    for key, value in os.environ.items():
+        raw = raw.replace(f"${{{key}}}", value)
+
+    parsed = yaml.safe_load(raw) or {}
+    CONFIG_CACHE = _normalize_config_paths(_strip_unresolved_placeholders(parsed))
+    return CONFIG_CACHE
+
+
+def is_remote_brain_only() -> bool:
+    cfg = load_config()
+    value = cfg.get("REMOTE_BRAIN_ONLY", os.getenv("REMOTE_BRAIN_ONLY", "0"))
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def setup_logging() -> None:
+    global _LOGGING_READY
+    if _LOGGING_READY:
+        return
+
+    log_cfg_path = os.path.join(os.path.dirname(__file__), "..", "config", "logging.yaml")
+    if not os.path.exists(log_cfg_path):
+        logging.basicConfig(level=logging.INFO)
+        _LOGGING_READY = True
+        return
+
+    try:
+        with open(log_cfg_path, "r", encoding="utf-8") as handle:
+            cfg = yaml.safe_load(handle) or {}
+        logging.config.dictConfig(cfg)
+    except Exception:
+        logging.basicConfig(level=logging.INFO)
+        logging.getLogger("kapo").warning("Falling back to basic logging configuration")
+
+    _LOGGING_READY = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    setup_logging()
+    return logging.getLogger(name)
+
+
+def _normalize_base_url(candidate: Any) -> str:
+    text = "" if candidate is None else str(candidate).strip()
+    if not text:
+        return ""
+    if "://" not in text:
+        text = f"http://{text}"
+    return text.rstrip("/")
+
+
+def get_executor_url(cfg: dict) -> str:
+    env_url = _normalize_base_url(os.getenv("EXECUTOR_URL"))
+    if env_url:
+        return env_url
+
+    cfg_url = _normalize_base_url(cfg.get("EXECUTOR_URL"))
+    if cfg_url:
+        return cfg_url
+
+    scheme = str(cfg.get("EXECUTOR_SCHEME") or os.getenv("EXECUTOR_SCHEME", "http")).strip() or "http"
+    host = str(cfg.get("EXECUTOR_HOST") or os.getenv("EXECUTOR_HOST", "localhost")).strip()
+    port = str(cfg.get("EXECUTOR_PORT") or os.getenv("EXECUTOR_PORT", "9000")).strip()
+
+    if "://" in host:
+        return host.rstrip("/")
+    if ":" in host:
+        return f"{scheme}://{host}".rstrip("/")
+    return f"{scheme}://{host}:{port}".rstrip("/")
+
+
+def get_executor_headers(cfg: dict) -> dict:
+    header = cfg.get("EXECUTOR_BYPASS_HEADER") or os.getenv("EXECUTOR_BYPASS_HEADER")
+    value = cfg.get("EXECUTOR_BYPASS_VALUE") or os.getenv("EXECUTOR_BYPASS_VALUE")
+    if header and value:
+        return {str(header): str(value)}
+    return {}
+
+
+def get_brain_headers(cfg: dict) -> dict:
+    header = cfg.get("BRAIN_BYPASS_HEADER") or os.getenv("BRAIN_BYPASS_HEADER")
+    value = cfg.get("BRAIN_BYPASS_VALUE") or os.getenv("BRAIN_BYPASS_VALUE")
+    if header and value:
+        return {str(header): str(value)}
+    return {}

brain_server/api/firebase_store.py

@@ -0,0 +1,356 @@
+"""Shared-state store for brain runtime via Google Drive, local files, or Firebase."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from shared.google_drive_state import GoogleDriveStateClient
+
+
+class FirebaseStore:
+    def __init__(self, component: str, logger_name: str = "kapo.brain.firebase") -> None:
+        self.component = component
+        self.logger = logging.getLogger(logger_name)
+        self._db = None
+        self._lock = threading.Lock()
+        self._read_cache: dict[str, tuple[float, Any]] = {}
+        self._list_cache: dict[str, tuple[float, list[dict[str, Any]]]] = {}
+        self._write_cache: dict[str, tuple[float, str]] = {}
+        self._quota_backoff_until: float = 0.0
+        self._drive = GoogleDriveStateClient(self.logger)
+
+    def backend(self) -> str:
+        configured = str(os.getenv("KAPO_SHARED_STATE_BACKEND", "")).strip().lower()
+        if configured in {"google_drive", "drive", "gdrive"}:
+            return "google_drive"
+        if configured in {"file", "files"}:
+            return "file"
+        if configured in {"firebase", "firestore"}:
+            return "firebase"
+        if configured in {"disabled", "off", "none"}:
+            return "disabled"
+        if self._drive.enabled():
+            return "google_drive"
+        if str(os.getenv("FIREBASE_ENABLED", "0")).strip().lower() in {"1", "true", "yes", "on"}:
+            return "firebase"
+        return "file"
+
+    def enabled(self) -> bool:
+        return self.backend() != "disabled"
+
+    def namespace(self) -> str:
+        return str(os.getenv("FIREBASE_NAMESPACE", "kapo")).strip() or "kapo"
+
+    def storage_root(self) -> Path:
+        configured = str(os.getenv("KAPO_SHARED_STATE_DIR", "")).strip()
+        if configured:
+            root = Path(configured).expanduser()
+            if not root.is_absolute():
+                root = Path.cwd().resolve() / root
+        else:
+            root = (Path.cwd().resolve() / "data" / "local" / "shared_state").resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        return root
+
+    def _service_payload(self) -> dict[str, Any] | None:
+        raw = str(os.getenv("FIREBASE_SERVICE_ACCOUNT_JSON", "")).strip()
+        if not raw:
+            return None
+        try:
+            return json.loads(raw)
+        except Exception:
+            self.logger.exception("Invalid Firebase service account JSON")
+            return None
+
+    @staticmethod
+    def _service_path() -> str:
+        return str(os.getenv("FIREBASE_SERVICE_ACCOUNT_PATH", "")).strip()
+
+    def _client(self):
+        if self.backend() != "firebase":
+            return None
+        with self._lock:
+            if self._db is not None:
+                return self._db
+            try:
+                import firebase_admin
+                from firebase_admin import credentials, firestore
+
+                if not firebase_admin._apps:
+                    payload = self._service_payload()
+                    if payload:
+                        cred = credentials.Certificate(payload)
+                    else:
+                        service_path = self._service_path()
+                        if not service_path:
+                            return None
+                        path_obj = Path(service_path).expanduser()
+                        if not path_obj.exists() or not path_obj.is_file():
+                            self.logger.warning(
+                                "Firebase service account path is unavailable on this runtime: %s",
+                                service_path,
+                            )
+                            return None
+                        cred = credentials.Certificate(str(path_obj.resolve()))
+                    options = {}
+                    project_id = str(os.getenv("FIREBASE_PROJECT_ID", "")).strip()
+                    if project_id:
+                        options["projectId"] = project_id
+                    firebase_admin.initialize_app(cred, options or None)
+                self._db = firestore.client()
+                return self._db
+            except Exception:
+                self.logger.exception("Failed to initialize Firebase client")
+                return None
+
+    def _collection(self, name: str) -> str:
+        return f"{self.namespace()}_{name}"
+
+    @staticmethod
+    def _safe_id(value: str, default: str = "default") -> str:
+        text = str(value or "").strip() or default
+        return "".join(ch if ch.isalnum() or ch in {"-", "_", "."} else "_" for ch in text)[:180]
+
+    @staticmethod
+    def _payload_hash(payload: Any) -> str:
+        return json.dumps(payload, ensure_ascii=False, sort_keys=True, default=str)
+
+    @staticmethod
+    def _is_quota_error(exc: Exception) -> bool:
+        text = str(exc or "").lower()
+        return "resourceexhausted" in text or "quota exceeded" in text or "429" in text
+
+    def _quota_backoff_active(self) -> bool:
+        return time.time() < self._quota_backoff_until
+
+    def _activate_quota_backoff(self, seconds: float | None = None) -> None:
+        delay = float(seconds or os.getenv("FIREBASE_QUOTA_BACKOFF_SEC", "120") or 120)
+        self._quota_backoff_until = max(self._quota_backoff_until, time.time() + max(5.0, delay))
+
+    def _should_skip_write(self, key: str, payload: Any, min_interval_sec: float) -> bool:
+        now = time.time()
+        payload_hash = self._payload_hash(payload)
+        last = self._write_cache.get(key)
+        if last and last[1] == payload_hash and (now - last[0]) < min_interval_sec:
+            return True
+        self._write_cache[key] = (now, payload_hash)
+        return False
+
+    def _file_collection_dir(self, collection: str) -> Path:
+        path = self.storage_root() / self._safe_id(collection, "collection")
+        path.mkdir(parents=True, exist_ok=True)
+        return path
+
+    def _file_doc_path(self, collection: str, doc_id: str) -> Path:
+        return self._file_collection_dir(collection) / f"{self._safe_id(doc_id)}.json"
+
+    def _write_json_atomic(self, path: Path, payload: dict[str, Any]) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(f"{path.suffix}.tmp")
+        tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+        tmp.replace(path)
+
+    def get_document(self, collection: str, doc_id: str, ttl_sec: float = 12.0) -> dict[str, Any]:
+        safe_doc = self._safe_id(doc_id)
+        cache_key = f"{collection}:{safe_doc}"
+        now = time.time()
+        cached = self._read_cache.get(cache_key)
+        if cached and (now - cached[0]) < ttl_sec:
+            return dict(cached[1] or {})
+        backend = self.backend()
+        if backend == "google_drive":
+            payload = self._drive.get_document(collection, safe_doc)
+            self._read_cache[cache_key] = (now, payload)
+            return dict(payload or {})
+        if backend == "file":
+            path = self._file_doc_path(collection, safe_doc)
+            if not path.exists():
+                return {}
+            try:
+                payload = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:
+                self.logger.warning("Failed to read shared-state file %s", path, exc_info=True)
+                return {}
+            self._read_cache[cache_key] = (now, payload)
+            return dict(payload or {})
+        if self._quota_backoff_active():
+            return dict(cached[1] or {}) if cached else {}
+        db = self._client()
+        if db is None:
+            return dict(cached[1] or {}) if cached else {}
+        try:
+            snapshot = db.collection(self._collection(collection)).document(safe_doc).get()
+            payload = snapshot.to_dict() if snapshot.exists else {}
+            self._read_cache[cache_key] = (now, payload)
+            return dict(payload or {})
+        except Exception as exc:
+            if self._is_quota_error(exc):
+                self._activate_quota_backoff()
+                self.logger.warning("Firebase quota exceeded while reading %s/%s; using cache/backoff", collection, safe_doc)
+            else:
+                self.logger.exception("Failed to read Firebase document %s/%s", collection, safe_doc)
+            return dict(cached[1] or {}) if cached else {}
+
+    def set_document(self, collection: str, doc_id: str, payload: dict[str, Any], merge: bool = True, min_interval_sec: float = 5.0) -> bool:
+        safe_doc = self._safe_id(doc_id)
+        cache_key = f"{collection}:{safe_doc}"
+        body = dict(payload or {})
+        body["component"] = self.component
+        body["updated_at"] = time.time()
+        if self._should_skip_write(cache_key, body, min_interval_sec):
+            return True
+        backend = self.backend()
+        if backend == "google_drive":
+            stored = self._drive.set_document(collection, safe_doc, body, merge=merge)
+            if stored:
+                self._read_cache.pop(cache_key, None)
+                stale_prefix = f"{collection}:list:"
+                for key in list(self._list_cache.keys()):
+                    if key.startswith(stale_prefix):
+                        self._list_cache.pop(key, None)
+            return stored
+        if backend == "file":
+            try:
+                path = self._file_doc_path(collection, safe_doc)
+                existing = {}
+                if merge and path.exists():
+                    existing = json.loads(path.read_text(encoding="utf-8"))
+                combined = {**existing, **body} if merge else body
+                combined.setdefault("id", safe_doc)
+                self._write_json_atomic(path, combined)
+                self._read_cache.pop(cache_key, None)
+                stale_prefix = f"{collection}:list:"
+                for key in list(self._list_cache.keys()):
+                    if key.startswith(stale_prefix):
+                        self._list_cache.pop(key, None)
+                return True
+            except Exception:
+                self.logger.warning("Failed to write shared-state file %s/%s", collection, safe_doc, exc_info=True)
+                return False
+        if self._quota_backoff_active():
+            return False
+        db = self._client()
+        if db is None:
+            return False
+        try:
+            if self._should_skip_write(cache_key, body, min_interval_sec):
+                return True
+            db.collection(self._collection(collection)).document(safe_doc).set(body, merge=merge)
+            self._read_cache.pop(cache_key, None)
+            stale_prefix = f"{collection}:list:"
+            for key in list(self._list_cache.keys()):
+                if key.startswith(stale_prefix):
+                    self._list_cache.pop(key, None)
+            return True
+        except Exception as exc:
+            if self._is_quota_error(exc):
+                self._activate_quota_backoff()
+                self.logger.warning("Firebase quota exceeded while writing %s/%s; write skipped", collection, safe_doc)
+            else:
+                self.logger.exception("Failed to write Firebase document %s/%s", collection, safe_doc)
+            return False
+
+    def list_documents(self, collection: str, limit: int = 200, ttl_sec: float = 30.0) -> list[dict[str, Any]]:
+        cache_key = f"{collection}:list:{max(1, int(limit))}"
+        now = time.time()
+        cached = self._list_cache.get(cache_key)
+        if cached and (now - cached[0]) < ttl_sec:
+            return [dict(item) for item in (cached[1] or [])]
+        backend = self.backend()
+        if backend == "google_drive":
+            items = self._drive.list_documents(collection, limit=max(1, int(limit)))
+            self._list_cache[cache_key] = (now, [dict(item) for item in items])
+            return items
+        if backend == "file":
+            items: list[dict[str, Any]] = []
+            try:
+                paths = sorted(
+                    self._file_collection_dir(collection).glob("*.json"),
+                    key=lambda path: path.stat().st_mtime,
+                    reverse=True,
+                )
+                for path in paths[: max(1, int(limit))]:
+                    payload = json.loads(path.read_text(encoding="utf-8"))
+                    payload.setdefault("id", path.stem)
+                    items.append(payload)
+            except Exception:
+                self.logger.warning("Failed to list shared-state files for %s", collection, exc_info=True)
+            self._list_cache[cache_key] = (now, [dict(item) for item in items])
+            return items
+        if self._quota_backoff_active():
+            return [dict(item) for item in ((cached[1] if cached else []) or [])]
+        db = self._client()
+        if db is None:
+            return [dict(item) for item in ((cached[1] if cached else []) or [])]
+        try:
+            docs = db.collection(self._collection(collection)).limit(max(1, int(limit))).stream()
+            items: list[dict[str, Any]] = []
+            for doc in docs:
+                payload = doc.to_dict() or {}
+                payload.setdefault("id", doc.id)
+                items.append(payload)
+            self._list_cache[cache_key] = (now, [dict(item) for item in items])
+            return items
+        except Exception as exc:
+            if self._is_quota_error(exc):
+                self._activate_quota_backoff()
+                self.logger.warning("Firebase quota exceeded while listing %s; using cache/backoff", collection)
+            else:
+                self.logger.exception("Failed to list Firebase collection %s", collection)
+            return [dict(item) for item in ((cached[1] if cached else []) or [])]
+
+    def delete_document(self, collection: str, doc_id: str) -> bool:
+        safe_doc = self._safe_id(doc_id)
+        backend = self.backend()
+        if backend == "google_drive":
+            deleted = self._drive.delete_document(collection, safe_doc)
+            if deleted:
+                self._read_cache.pop(f"{collection}:{safe_doc}", None)
+                self._write_cache.pop(f"{collection}:{safe_doc}", None)
+                stale_prefix = f"{collection}:list:"
+                for key in list(self._list_cache.keys()):
+                    if key.startswith(stale_prefix):
+                        self._list_cache.pop(key, None)
+            return deleted
+        if backend == "file":
+            try:
+                path = self._file_doc_path(collection, safe_doc)
+                if path.exists():
+                    path.unlink()
+                self._read_cache.pop(f"{collection}:{safe_doc}", None)
+                self._write_cache.pop(f"{collection}:{safe_doc}", None)
+                stale_prefix = f"{collection}:list:"
+                for key in list(self._list_cache.keys()):
+                    if key.startswith(stale_prefix):
+                        self._list_cache.pop(key, None)
+                return True
+            except Exception:
+                self.logger.warning("Failed to delete shared-state file %s/%s", collection, safe_doc, exc_info=True)
+                return False
+        if self._quota_backoff_active():
+            return False
+        db = self._client()
+        if db is None:
+            return False
+        try:
+            db.collection(self._collection(collection)).document(safe_doc).delete()
+            self._read_cache.pop(f"{collection}:{safe_doc}", None)
+            self._write_cache.pop(f"{collection}:{safe_doc}", None)
+            stale_prefix = f"{collection}:list:"
+            for key in list(self._list_cache.keys()):
+                if key.startswith(stale_prefix):
+                    self._list_cache.pop(key, None)
+            return True
+        except Exception as exc:
+            if self._is_quota_error(exc):
+                self._activate_quota_backoff()
+                self.logger.warning("Firebase quota exceeded while deleting %s/%s; delete skipped", collection, safe_doc)
+            else:
+                self.logger.exception("Failed to delete Firebase document %s/%s", collection, safe_doc)
+            return False

brain_server/api/main.py

@@ -0,0 +1,2356 @@
+"""FastAPI entrypoint for the Brain Server."""
+import base64
+import gc
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import zipfile
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+import requests
+from fastapi import FastAPI, File, UploadFile
+from pydantic import BaseModel
+
+from agents.memory_agent import MemoryAgent
+from agents.planner_agent import PlannerAgent
+from agents.reasoning_agent import ReasoningAgent
+try:
+    from api import deps as deps_module
+    from api.deps import get_executor_headers, get_logger, load_config
+    from api.firebase_store import FirebaseStore
+    from api.routes_analyze import router as analyze_router
+    from api.routes_execute import router as execute_router
+    from api.routes_plan import router as plan_router
+    from shared.google_drive_state import GoogleDriveStateClient
+except ImportError:
+    from . import deps as deps_module
+    from .deps import get_executor_headers, get_logger, load_config
+    from .firebase_store import FirebaseStore
+    from .routes_analyze import router as analyze_router
+    from .routes_execute import router as execute_router
+    from .routes_plan import router as plan_router
+    from shared.google_drive_state import GoogleDriveStateClient
+
+logger = get_logger("kapo.brain.main")
+
+
+def _configure_windows_utf8() -> None:
+    if os.name != "nt":
+        return
+    os.environ.setdefault("PYTHONUTF8", "1")
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    os.environ.setdefault("PYTHONLEGACYWINDOWSSTDIO", "utf-8")
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        kernel32.SetConsoleCP(65001)
+        kernel32.SetConsoleOutputCP(65001)
+    except Exception:
+        pass
+
+
+_configure_windows_utf8()
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+app = FastAPI(title="KAPO-AI Brain Server", version="1.0.0")
+app.include_router(plan_router)
+app.include_router(execute_router)
+app.include_router(analyze_router)
+
+MODEL = None
+MODEL_ERROR = None
+MODEL_META = {"repo_id": None, "filename": None, "path": None}
+EMBED_MODEL = None
+FIREBASE = FirebaseStore("brain", logger_name="kapo.brain.firebase")
+DRIVE_STATE = GoogleDriveStateClient(logger)
+FIREBASE_RUNTIME_CACHE: dict[str, tuple[float, Any]] = {}
+RUNTIME_LOG_BUFFER: deque[dict[str, Any]] = deque(maxlen=200)
+LAST_BRAIN_URL_REPORT: dict[str, Any] = {"url": "", "ts": 0.0}
+RUNTIME_STATE_THREAD_STARTED = False
+
+DEFAULT_MODEL_REPO = "QuantFactory/aya-expanse-8b-GGUF"
+DEFAULT_MODEL_FILE = "aya-expanse-8b.Q4_K_M.gguf"
+DEFAULT_MODEL_PROFILE_ID = "supervisor-ar-en-default"
+HAS_MULTIPART = True
+try:
+    import multipart  # noqa: F401
+except Exception:
+    HAS_MULTIPART = False
+
+
+class RuntimeLogHandler(logging.Handler):
+    def emit(self, record) -> None:
+        try:
+            RUNTIME_LOG_BUFFER.append(
+                {
+                    "ts": time.time(),
+                    "level": record.levelname,
+                    "name": record.name,
+                    "message": record.getMessage(),
+                }
+            )
+        except Exception:
+            pass
+
+
+_runtime_log_handler = RuntimeLogHandler(level=logging.WARNING)
+if not any(isinstance(handler, RuntimeLogHandler) for handler in logger.handlers):
+    logger.addHandler(_runtime_log_handler)
+
+
+def _feature_enabled(name: str, default: bool = False) -> bool:
+    value = os.getenv(name)
+    if value is None or str(value).strip() == "":
+        return default
+    return str(value).strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _remote_brain_only() -> bool:
+    return _feature_enabled("REMOTE_BRAIN_ONLY", default=False)
+
+
+def _ngrok_bootstrap_enabled() -> bool:
+    return _feature_enabled("BRAIN_AUTO_NGROK", default=True)
+
+
+def _configured_public_url() -> str:
+    return str(os.getenv("BRAIN_PUBLIC_URL", "")).strip().rstrip("/")
+
+
+def _prefer_configured_public_url() -> bool:
+    provider = str(os.getenv("BRAIN_PROVIDER", "") or os.getenv("BRAIN_TEMPLATE", "")).strip().lower()
+    if "huggingface" in provider or "hf-space" in provider:
+        return True
+    return _feature_enabled("BRAIN_FORCE_CONFIGURED_PUBLIC_URL", default=False)
+
+
+def _reuse_public_url_on_restart() -> bool:
+    return _feature_enabled("BRAIN_REUSE_PUBLIC_URL_ON_RESTART", default=True)
+
+
+def _auto_publish_public_url_on_startup() -> bool:
+    return _feature_enabled("BRAIN_AUTO_PUBLISH_URL_ON_STARTUP", default=True)
+
+
+def _internal_restart_in_progress() -> bool:
+    return _feature_enabled("KAPO_INTERNAL_RESTART", default=False)
+
+
+def _fast_restart_enabled() -> bool:
+    return _feature_enabled("KAPO_FAST_INTERNAL_RESTART", default=True)
+
+
+def _executor_connect_timeout() -> float:
+    return float(os.getenv("EXECUTOR_CONNECT_TIMEOUT_SEC", "3.0") or 3.0)
+
+
+def _executor_read_timeout(name: str, default: float) -> float:
+    return float(os.getenv(name, str(default)) or default)
+
+
+def _executor_roundtrip_allowed(feature_name: str, default: bool = True) -> bool:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip()
+    if not executor_url:
+        return False
+    kaggle_defaults = {
+        "BRAIN_REMOTE_TRACE_STORE_ENABLED": False,
+        "BRAIN_REMOTE_AUTO_INGEST_ENABLED": False,
+        "BRAIN_REMOTE_STYLE_PROFILE_ENABLED": False,
+    }
+    effective_default = kaggle_defaults.get(feature_name, default) if _is_kaggle_runtime() else default
+    return _feature_enabled(feature_name, default=effective_default)
+
+
+def _remote_runtime_reads_enabled() -> bool:
+    return _feature_enabled("KAPO_REMOTE_STATE_READS", default=False)
+
+
+def _shared_state_backend() -> str:
+    return str(os.getenv("KAPO_SHARED_STATE_BACKEND", "")).strip().lower()
+
+
+def _drive_bootstrap_configured() -> bool:
+    return bool(
+        str(os.getenv("GOOGLE_DRIVE_BOOTSTRAP_URL", "") or os.getenv("KAPO_BOOTSTRAP_URL", "") or "").strip()
+    )
+
+
+def _bootstrap_shared_state() -> None:
+    if _drive_bootstrap_configured() or _shared_state_backend() in {"google_drive", "drive", "gdrive"}:
+        DRIVE_STATE.ensure_bootstrap_loaded(force=False)
+
+
+def _startup_self_update_enabled() -> bool:
+    return _feature_enabled("KAPO_STARTUP_SELF_UPDATE", default=True)
+
+
+def _should_report_brain_url(public_url: str) -> bool:
+    normalized = str(public_url or "").strip().rstrip("/")
+    if not normalized:
+        return False
+    interval_sec = max(30.0, float(os.getenv("BRAIN_REPORT_MIN_INTERVAL_SEC", "600") or 600))
+    previous_url = str(LAST_BRAIN_URL_REPORT.get("url") or "").strip()
+    previous_ts = float(LAST_BRAIN_URL_REPORT.get("ts") or 0.0)
+    now = time.time()
+    if normalized != previous_url or (now - previous_ts) >= interval_sec:
+        LAST_BRAIN_URL_REPORT["url"] = normalized
+        LAST_BRAIN_URL_REPORT["ts"] = now
+        return True
+    return False
+
+
+def _download_model(repo_id: str, filename: str, hf_token: str | None = None) -> str:
+    from huggingface_hub import hf_hub_download
+
+    configured_cache = str(os.getenv("MODEL_CACHE_DIR", "") or "").strip()
+    if configured_cache:
+        cache_dir = configured_cache
+    elif _is_kaggle_runtime():
+        cache_dir = str((_project_root() / "models_cache").resolve())
+    else:
+        cache_dir = os.path.join(tempfile.gettempdir(), "kapo_models")
+    os.makedirs(cache_dir, exist_ok=True)
+    return hf_hub_download(repo_id=repo_id, filename=filename, cache_dir=cache_dir, token=hf_token)
+
+
+def ensure_model_loaded(repo_id: str, filename: str, hf_token: str | None = None) -> None:
+    global MODEL, MODEL_ERROR, MODEL_META
+    repo_id = (repo_id or "").strip()
+    filename = (filename or "").strip()
+    if not repo_id or not filename:
+        MODEL = None
+        MODEL_ERROR = "model repo/file missing"
+        return
+
+    try:
+        model_path = _download_model(repo_id, filename, hf_token=hf_token)
+    except Exception as exc:
+        MODEL = None
+        MODEL_ERROR = f"model download failed: {exc}"
+        logger.exception("Model download failed")
+        return
+
+    try:
+        from llama_cpp import Llama
+
+        MODEL = Llama(model_path=model_path, n_ctx=4096)
+        MODEL_ERROR = None
+        MODEL_META = {"repo_id": repo_id, "filename": filename, "path": model_path}
+        logger.info("Loaded model %s/%s", repo_id, filename)
+    except Exception as exc:
+        MODEL = None
+        MODEL_ERROR = f"model load failed: {exc}"
+        logger.exception("Model load failed")
+
+
+def _load_embed_model() -> None:
+    global EMBED_MODEL
+    if EMBED_MODEL is not None:
+        return
+
+    from sentence_transformers import SentenceTransformer
+
+    model_name = os.getenv("EMBED_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+    EMBED_MODEL = SentenceTransformer(model_name)
+    logger.info("Loaded embedding model %s", model_name)
+
+
+def _load_default_model() -> None:
+    repo_id = os.getenv("MODEL_REPO", DEFAULT_MODEL_REPO)
+    filename = os.getenv("MODEL_FILE", DEFAULT_MODEL_FILE)
+    ensure_model_loaded(repo_id, filename, hf_token=os.getenv("HF_TOKEN"))
+
+
+def _brain_headers() -> dict:
+    cfg = load_config()
+    return get_executor_headers(cfg)
+
+
+def _project_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _is_kaggle_runtime() -> bool:
+    return "/kaggle/" in str(_project_root()).replace("\\", "/") or bool(os.getenv("KAGGLE_KERNEL_RUN_TYPE"))
+
+
+def _is_hf_space_runtime() -> bool:
+    return str(os.getenv("HF_SPACE_DOCKER", "0")).strip().lower() in {"1", "true", "yes", "on"} or bool(os.getenv("SPACE_ID"))
+
+
+def _apply_executor_settings(settings: dict[str, Any]) -> None:
+    for key in (
+        "NGROK_AUTHTOKEN",
+        "MODEL_REPO",
+        "MODEL_FILE",
+        "MODEL_PROFILE_ID",
+        "SUPERVISOR_MODEL_PROFILE_ID",
+        "EMBED_MODEL",
+        "REQUEST_TIMEOUT_SEC",
+        "REQUEST_RETRIES",
+        "CHAT_TIMEOUT_SEC",
+        "EXECUTOR_BYPASS_HEADER",
+        "EXECUTOR_BYPASS_VALUE",
+        "BRAIN_BYPASS_HEADER",
+        "BRAIN_BYPASS_VALUE",
+        "REMOTE_BRAIN_ONLY",
+        "KAGGLE_AUTO_BOOTSTRAP",
+        "BRAIN_AUTO_NGROK",
+        "BRAIN_AUTO_PUBLISH_URL_ON_STARTUP",
+        "BRAIN_PUBLIC_URL",
+        "BRAIN_REUSE_PUBLIC_URL_ON_RESTART",
+        "KAGGLE_SYNC_SUBDIR",
+        "BRAIN_ROLES",
+        "BRAIN_LANGUAGES",
+        "BRAIN_REMOTE_KNOWLEDGE_ENABLED",
+        "BRAIN_REMOTE_WEB_SEARCH_ENABLED",
+        "BRAIN_REMOTE_TRACE_STORE_ENABLED",
+        "BRAIN_REMOTE_AUTO_INGEST_ENABLED",
+        "BRAIN_LOCAL_RAG_FALLBACK_ENABLED",
+        "EXECUTOR_CONNECT_TIMEOUT_SEC",
+        "BRAIN_REMOTE_KNOWLEDGE_TIMEOUT_SEC",
+        "BRAIN_REMOTE_WEB_SEARCH_TIMEOUT_SEC",
+        "BRAIN_REMOTE_TRACE_STORE_TIMEOUT_SEC",
+        "BRAIN_REMOTE_AUTO_INGEST_TIMEOUT_SEC",
+        "FIREBASE_ENABLED",
+        "FIREBASE_PROJECT_ID",
+        "FIREBASE_SERVICE_ACCOUNT_PATH",
+        "FIREBASE_SERVICE_ACCOUNT_JSON",
+        "FIREBASE_NAMESPACE",
+        "KAPO_SHARED_STATE_BACKEND",
+        "GOOGLE_DRIVE_SHARED_STATE_FOLDER_ID",
+        "GOOGLE_DRIVE_SHARED_STATE_PREFIX",
+        "GOOGLE_DRIVE_BOOTSTRAP_URL",
+        "KAPO_BOOTSTRAP_URL",
+        "GOOGLE_DRIVE_ACCESS_TOKEN",
+        "GOOGLE_DRIVE_REFRESH_TOKEN",
+        "GOOGLE_DRIVE_CLIENT_SECRET_JSON",
+        "GOOGLE_DRIVE_CLIENT_SECRET_JSON_BASE64",
+        "GOOGLE_DRIVE_CLIENT_SECRET_PATH",
+        "GOOGLE_DRIVE_TOKEN_EXPIRES_AT",
+        "KAPO_CONTROL_PLANE_URL",
+        "KAPO_CLOUDFLARE_QUEUE_NAME",
+    ):
+        value = settings.get(key)
+        if value not in (None, ""):
+            os.environ[key] = str(value)
+    deps_module.CONFIG_CACHE = None
+
+
+def _apply_firebase_runtime_settings() -> None:
+    if not _remote_runtime_reads_enabled():
+        return
+    if not FIREBASE.enabled():
+        return
+    shared = FIREBASE.get_document("settings", "global")
+    runtime = FIREBASE.get_document("runtime", "executor")
+    role_items = FIREBASE.list_documents("roles", limit=64)
+    merged = {}
+    merged.update(shared or {})
+    merged.update(runtime or {})
+    mappings = {
+        "executor_public_url": "EXECUTOR_PUBLIC_URL",
+        "executor_url": "EXECUTOR_URL",
+        "model_repo": "MODEL_REPO",
+        "model_file": "MODEL_FILE",
+        "model_profile_id": "MODEL_PROFILE_ID",
+        "supervisor_model_profile_id": "SUPERVISOR_MODEL_PROFILE_ID",
+        "brain_roles": "BRAIN_ROLES",
+        "brain_languages": "BRAIN_LANGUAGES",
+    }
+    current_brain_url = str(merged.get("current_brain_url") or "").strip()
+    if current_brain_url:
+        os.environ["KAPO_EXECUTOR_CURRENT_BRAIN_URL"] = current_brain_url
+    for key, env_name in mappings.items():
+        value = merged.get(key)
+        if value not in (None, ""):
+            os.environ[env_name] = str(value)
+    if role_items:
+        enabled_roles = [
+            str(item.get("name") or item.get("id") or "").strip().lower()
+            for item in role_items
+            if str(item.get("enabled", True)).strip().lower() not in {"0", "false", "no", "off"}
+        ]
+        enabled_roles = [role for role in enabled_roles if role]
+        if enabled_roles:
+            os.environ["BRAIN_ROLES"] = ",".join(dict.fromkeys(enabled_roles))
+    deps_module.CONFIG_CACHE = None
+
+
+def _firebase_collection_cache_key(name: str) -> str:
+    return f"collection:{name}"
+
+
+def _firebase_list_documents_cached(collection: str, ttl_sec: float = 30.0, limit: int = 200) -> list[dict[str, Any]]:
+    if not _remote_runtime_reads_enabled():
+        return []
+    if not FIREBASE.enabled():
+        return []
+    key = _firebase_collection_cache_key(collection)
+    now = time.time()
+    cached = FIREBASE_RUNTIME_CACHE.get(key)
+    if cached and (now - cached[0]) < ttl_sec:
+        return list(cached[1] or [])
+    items = FIREBASE.list_documents(collection, limit=limit)
+    FIREBASE_RUNTIME_CACHE[key] = (now, items)
+    return list(items or [])
+
+
+def _firebase_role_profiles() -> list[dict[str, Any]]:
+    items = _firebase_list_documents_cached("roles", ttl_sec=30.0, limit=64)
+    if items:
+        return items
+    roles = [part.strip() for part in str(os.getenv("BRAIN_ROLES", "")).split(",") if part.strip()]
+    return [{"name": role, "enabled": True} for role in roles]
+
+
+def _firebase_runtime_snapshot() -> dict[str, Any]:
+    return {
+        "platforms": _firebase_list_documents_cached("platforms", ttl_sec=45.0, limit=64),
+        "models": _firebase_list_documents_cached("models", ttl_sec=45.0, limit=128),
+        "prompts": _firebase_list_documents_cached("prompts", ttl_sec=20.0, limit=128),
+        "roles": _firebase_role_profiles(),
+    }
+
+
+def _json_safe(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): _json_safe(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, tuple):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)
+
+
+def _firebase_prompt_body(role_name: str, language: str = "en") -> str:
+    role_name = str(role_name or "").strip().lower()
+    language = str(language or "en").strip().lower()
+    if not role_name:
+        return ""
+    prompts = _firebase_runtime_snapshot().get("prompts", [])
+    exact = []
+    fallback = []
+    for item in prompts:
+        if str(item.get("role_name") or "").strip().lower() != role_name:
+            continue
+        if str(item.get("enabled", True)).strip().lower() in {"0", "false", "no", "off"}:
+            continue
+        item_lang = str(item.get("language") or "en").strip().lower()
+        body = str(item.get("body") or "").strip()
+        if not body:
+            continue
+        if item_lang == language:
+            exact.append(body)
+        elif item_lang == "en":
+            fallback.append(body)
+    if exact:
+        return exact[0]
+    if fallback:
+        return fallback[0]
+    return ""
+
+
+def _prepare_runtime_environment() -> None:
+    try:
+        _bootstrap_shared_state()
+    except Exception:
+        logger.warning("Shared-state bootstrap preload failed", exc_info=True)
+    if not _is_kaggle_runtime():
+        return
+
+    source_root = _project_root()
+    source_text = str(source_root).replace("\\", "/")
+    runtime_root_env = os.getenv("KAPO_RUNTIME_ROOT", "").strip()
+    if runtime_root_env:
+        runtime_root = Path(runtime_root_env).resolve()
+    elif source_text.startswith("/kaggle/working/"):
+        runtime_root = source_root.resolve()
+    else:
+        runtime_root = Path("/kaggle/working/KAPO-AI-SYSTEM").resolve()
+    sync_root = runtime_root
+    auto_bootstrap = str(os.getenv("KAGGLE_AUTO_BOOTSTRAP", "1")).strip().lower() in {"1", "true", "yes", "on"}
+
+    if auto_bootstrap and source_text.startswith("/kaggle/input/") and source_root != runtime_root:
+        if runtime_root.exists():
+            shutil.rmtree(runtime_root, ignore_errors=True)
+        shutil.copytree(
+            source_root,
+            runtime_root,
+            ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".git", ".venv"),
+        )
+        if str(runtime_root) not in sys.path:
+            sys.path.insert(0, str(runtime_root))
+
+    data_dir = runtime_root / "data" / "local" / "brain_runtime"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    os.environ["KAPO_RUNTIME_ROOT"] = str(runtime_root)
+    os.environ["KAPO_SYNC_ROOT"] = str(sync_root)
+    os.environ["LOCAL_DATA_DIR"] = str(data_dir)
+    os.environ["DB_PATH"] = str(data_dir / "episodic.db")
+    os.environ["TOOLS_DB_PATH"] = str(data_dir / "tools.db")
+    os.environ["FAISS_INDEX_PATH"] = str(data_dir / "faiss.index")
+    os.environ["REMOTE_BRAIN_ONLY"] = str(os.getenv("REMOTE_BRAIN_ONLY", "1") or "1")
+    saved_executor_url = _load_saved_executor_url()
+    current_executor_url = str(os.getenv("EXECUTOR_URL", "") or "").strip()
+    if saved_executor_url and not current_executor_url:
+        os.environ["EXECUTOR_URL"] = saved_executor_url
+    deps_module.CONFIG_CACHE = None
+
+
+def _sync_target_root() -> str:
+    return os.getenv("KAPO_SYNC_ROOT") or os.getenv("KAPO_RUNTIME_ROOT") or os.getcwd()
+
+
+def _sync_root_path() -> Path:
+    return Path(_sync_target_root()).resolve()
+
+
+def _resolve_sync_path(user_path: str | None = None) -> Path:
+    root = _sync_root_path()
+    relative = str(user_path or "").strip().replace("\\", "/").lstrip("/")
+    candidate = (root / relative).resolve() if relative else root
+    if candidate != root and root not in candidate.parents:
+        raise ValueError("Path escapes sync root")
+    return candidate
+
+
+def _describe_sync_entry(path: Path) -> dict[str, Any]:
+    stat = path.stat()
+    return {
+        "name": path.name or str(path),
+        "path": str(path.relative_to(_sync_root_path())).replace("\\", "/") if path != _sync_root_path() else "",
+        "is_dir": path.is_dir(),
+        "size": stat.st_size,
+        "modified_at": stat.st_mtime,
+    }
+
+
+def _public_url_state_path() -> Path:
+    runtime_root = Path(_sync_target_root()).resolve()
+    state_dir = runtime_root / "data" / "local" / "brain_runtime"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "public_url.txt"
+
+
+def _remember_public_url(public_url: str) -> None:
+    value = str(public_url or "").strip().rstrip("/")
+    if not value:
+        return
+    os.environ["BRAIN_PUBLIC_URL"] = value
+    try:
+        _public_url_state_path().write_text(value, encoding="utf-8")
+    except Exception:
+        logger.warning("Failed to persist public URL", exc_info=True)
+
+
+def _load_saved_public_url() -> str:
+    try:
+        value = _public_url_state_path().read_text(encoding="utf-8").strip().rstrip("/")
+        return value
+    except Exception:
+        return ""
+
+
+def _ngrok_api_state_path() -> Path:
+    runtime_root = Path(_sync_target_root()).resolve()
+    state_dir = runtime_root / "data" / "local" / "brain_runtime"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "ngrok_api_url.txt"
+
+
+def _executor_url_state_path() -> Path:
+    runtime_root = Path(_sync_target_root()).resolve()
+    state_dir = runtime_root / "data" / "local" / "brain_runtime"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "executor_url.txt"
+
+
+def _remember_executor_url(executor_url: str) -> None:
+    value = str(executor_url or "").strip().rstrip("/")
+    if not value:
+        return
+    os.environ["EXECUTOR_URL"] = value
+    try:
+        _executor_url_state_path().write_text(value, encoding="utf-8")
+    except Exception:
+        logger.warning("Failed to persist executor URL", exc_info=True)
+
+
+def _load_saved_executor_url() -> str:
+    configured = str(os.getenv("EXECUTOR_URL", "")).strip().rstrip("/")
+    if configured:
+        return configured
+    try:
+        return _executor_url_state_path().read_text(encoding="utf-8").strip().rstrip("/")
+    except Exception:
+        return ""
+
+
+def _brain_state_id() -> str:
+    public_url = str(os.getenv("BRAIN_PUBLIC_URL") or _load_saved_public_url() or "").strip().rstrip("/")
+    if public_url:
+        return re.sub(r"[^A-Za-z0-9._-]+", "_", public_url)
+    runtime_root = str(os.getenv("KAPO_RUNTIME_ROOT") or _sync_target_root() or "brain_runtime").strip()
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", runtime_root)
+
+
+def _applied_runtime_version_path() -> Path:
+    runtime_root = Path(_sync_target_root()).resolve()
+    state_dir = runtime_root / "data" / "local" / "brain_runtime"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "applied_version.json"
+
+
+def _load_applied_runtime_version() -> dict[str, Any]:
+    try:
+        return dict(json.loads(_applied_runtime_version_path().read_text(encoding="utf-8")) or {})
+    except Exception:
+        return {}
+
+
+def _write_applied_runtime_version(payload: dict[str, Any]) -> None:
+    _applied_runtime_version_path().write_text(
+        json.dumps(dict(payload or {}), ensure_ascii=False, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )
+
+
+def _download_remote_zip(url: str, destination: Path) -> Path:
+    response = requests.get(str(url).strip(), timeout=120)
+    response.raise_for_status()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_bytes(response.content)
+    return destination
+
+
+def _apply_zip_overlay(zip_path: Path, target_root: Path) -> None:
+    with zipfile.ZipFile(zip_path, "r") as archive:
+        archive.extractall(target_root)
+
+
+def _load_patch_manifest_from_bootstrap() -> dict[str, Any]:
+    bootstrap = DRIVE_STATE.ensure_bootstrap_loaded(force=True) or {}
+    manifest_url = str(bootstrap.get("patch_manifest_url") or "").strip()
+    if not manifest_url:
+        return dict(bootstrap)
+    try:
+        response = requests.get(manifest_url, timeout=30)
+        response.raise_for_status()
+        payload = dict(response.json() or {})
+        merged = {**bootstrap, **payload}
+        return merged
+    except Exception:
+        logger.warning("Failed to load patch manifest from bootstrap URL", exc_info=True)
+        return dict(bootstrap)
+
+
+def _run_startup_self_update() -> None:
+    if not _startup_self_update_enabled():
+        return
+    manifest = _load_patch_manifest_from_bootstrap()
+    target_version = str(manifest.get("version") or "").strip()
+    target_hash = str(manifest.get("build_hash") or "").strip()
+    if not target_version and not target_hash:
+        return
+    current = _load_applied_runtime_version()
+    if (
+        str(current.get("version") or "").strip() == target_version
+        and str(current.get("build_hash") or "").strip() == target_hash
+        and target_version
+    ):
+        return
+    runtime_root = Path(_sync_target_root()).resolve()
+    temp_dir = runtime_root / "data" / "local" / "brain_runtime" / "updates"
+    patch_url = str(manifest.get("patch_bundle_url") or "").strip()
+    full_url = str(manifest.get("full_package_url") or "").strip()
+    applied_mode = ""
+    source_url = ""
+    try:
+        if patch_url:
+            zip_path = _download_remote_zip(patch_url, temp_dir / "patch_bundle.zip")
+            _apply_zip_overlay(zip_path, runtime_root)
+            applied_mode = "patch_bundle"
+            source_url = patch_url
+        elif full_url:
+            zip_path = _download_remote_zip(full_url, temp_dir / "full_package.zip")
+            _apply_zip_overlay(zip_path, runtime_root)
+            applied_mode = "full_package"
+            source_url = full_url
+        else:
+            return
+        _write_applied_runtime_version(
+            {
+                "version": target_version,
+                "build_hash": target_hash,
+                "applied_at": time.time(),
+                "mode": applied_mode,
+                "source_url": source_url,
+            }
+        )
+        logger.info("Applied startup self-update (%s) version=%s", applied_mode, target_version or target_hash)
+    except Exception:
+        logger.warning("Startup self-update failed", exc_info=True)
+
+
+def _remember_ngrok_api_url(api_url: str) -> None:
+    value = str(api_url or "").strip().rstrip("/")
+    if not value:
+        return
+    os.environ["KAPO_NGROK_API_URL"] = value
+    try:
+        _ngrok_api_state_path().write_text(value, encoding="utf-8")
+    except Exception:
+        logger.warning("Failed to persist ngrok API URL", exc_info=True)
+
+
+def _load_saved_ngrok_api_url() -> str:
+    configured = str(os.getenv("KAPO_NGROK_API_URL", "")).strip().rstrip("/")
+    if configured:
+        return configured
+    try:
+        return _ngrok_api_state_path().read_text(encoding="utf-8").strip().rstrip("/")
+    except Exception:
+        return ""
+
+
+def _ngrok_api_candidates() -> list[str]:
+    seen: set[str] = set()
+    candidates: list[str] = []
+    for candidate in [_load_saved_ngrok_api_url(), "http://127.0.0.1:4040", "http://127.0.0.1:4041", "http://127.0.0.1:4042"]:
+        value = str(candidate or "").strip().rstrip("/")
+        if value and value not in seen:
+            seen.add(value)
+            candidates.append(value)
+    return candidates
+
+
+def _probe_ngrok_api(api_url: str) -> bool:
+    try:
+        response = requests.get(f"{api_url}/api/tunnels", timeout=2)
+        return response.status_code == 200
+    except Exception:
+        return False
+
+
+def _find_live_ngrok_api() -> str | None:
+    for api_url in _ngrok_api_candidates():
+        if _probe_ngrok_api(api_url):
+            _remember_ngrok_api_url(api_url)
+            return api_url
+    return None
+
+
+def _ngrok_binary_path() -> str:
+    env_path = str(os.getenv("NGROK_PATH", "")).strip()
+    if env_path and Path(env_path).exists():
+        return env_path
+    default_ngrok_path = ""
+    try:
+        from pyngrok import conf
+
+        default_ngrok_path = str(conf.get_default().ngrok_path or "").strip()
+        if default_ngrok_path and Path(default_ngrok_path).exists():
+            return default_ngrok_path
+    except Exception:
+        pass
+    try:
+        from pyngrok import installer
+
+        install_target = default_ngrok_path or str((Path.home() / ".ngrok" / "ngrok").resolve())
+        Path(install_target).parent.mkdir(parents=True, exist_ok=True)
+        installer.install_ngrok(install_target)
+        if Path(install_target).exists():
+            return install_target
+    except Exception:
+        logger.warning("Failed to auto-install ngrok binary", exc_info=True)
+    discovered = shutil.which("ngrok")
+    if discovered:
+        return discovered
+    return "ngrok"
+
+
+def _ensure_ngrok_auth(token: str) -> None:
+    ngrok_path = _ngrok_binary_path()
+    subprocess.run(
+        [ngrok_path, "config", "add-authtoken", token],
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+
+def _start_detached_ngrok_agent(token: str) -> str | None:
+    if token:
+        _ensure_ngrok_auth(token)
+        os.environ["NGROK_AUTHTOKEN"] = token
+
+    ngrok_path = _ngrok_binary_path()
+    popen_kwargs = {
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "stdin": subprocess.DEVNULL,
+    }
+    if os.name == "nt":
+        popen_kwargs["creationflags"] = getattr(subprocess, "DETACHED_PROCESS", 0) | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    else:
+        popen_kwargs["start_new_session"] = True
+
+    subprocess.Popen(
+        [ngrok_path, "start", "--none", "--log=stdout"],
+        **popen_kwargs,
+    )
+
+    deadline = time.time() + 12
+    while time.time() < deadline:
+        api_url = _find_live_ngrok_api()
+        if api_url:
+            return api_url
+        time.sleep(0.5)
+    return None
+
+
+def _list_ngrok_tunnels(api_url: str) -> list[dict[str, Any]]:
+    response = requests.get(f"{api_url}/api/tunnels", timeout=5)
+    response.raise_for_status()
+    payload = response.json()
+    tunnels = payload.get("tunnels")
+    return tunnels if isinstance(tunnels, list) else []
+
+
+def _existing_ngrok_public_url(api_url: str, port: int) -> str | None:
+    for tunnel in _list_ngrok_tunnels(api_url):
+        public_url = str(tunnel.get("public_url") or "").strip()
+        config = tunnel.get("config") or {}
+        addr = str(config.get("addr") or "").strip()
+        if public_url and addr.endswith(f":{port}"):
+            return public_url.rstrip("/")
+    return None
+
+
+def _create_ngrok_tunnel(api_url: str, port: int) -> str | None:
+    response = requests.post(
+        f"{api_url}/api/tunnels",
+        json={
+            "name": f"http-{port}-kapo",
+            "addr": str(port),
+            "proto": "http",
+        },
+        timeout=10,
+    )
+    response.raise_for_status()
+    payload = response.json()
+    return str(payload.get("public_url") or "").strip().rstrip("/") or None
+
+
+def _publish_brain_presence(public_url: str, *, source: str = "runtime") -> None:
+    normalized = str(public_url or "").strip().rstrip("/")
+    if not normalized:
+        return
+    payload = {
+        "url": normalized,
+        "status": "healthy",
+        "source": source,
+        "platform": "kaggle" if _is_kaggle_runtime() else str(os.getenv("BRAIN_PROVIDER") or "remote"),
+        "role": os.getenv("BRAIN_PRIMARY_ROLE", "fallback"),
+        "roles": [part.strip() for part in os.getenv("BRAIN_ROLES", "supervisor,chat,coding,planner,arabic,fallback").split(",") if part.strip()],
+        "languages": [part.strip() for part in os.getenv("BRAIN_LANGUAGES", "ar,en").split(",") if part.strip()],
+        "model_profile_id": os.getenv("MODEL_PROFILE_ID") or os.getenv("SUPERVISOR_MODEL_PROFILE_ID") or DEFAULT_MODEL_PROFILE_ID,
+        "model_repo": MODEL_META.get("repo_id") or os.getenv("MODEL_REPO") or DEFAULT_MODEL_REPO,
+        "model_file": MODEL_META.get("filename") or os.getenv("MODEL_FILE") or DEFAULT_MODEL_FILE,
+        "updated_at": time.time(),
+    }
+    FIREBASE.set_document("brains", normalized, payload)
+    FIREBASE.set_document(
+        "runtime",
+        "brains_last_report",
+        {
+            "brain_url": normalized,
+            "source": source,
+            "updated_at": time.time(),
+            "provider": payload["platform"],
+            "model_profile_id": payload["model_profile_id"],
+        },
+    )
+    FIREBASE.set_document(
+        "tunnels",
+        f"brain_{normalized}",
+        {
+            "kind": "brain",
+            "public_url": normalized,
+            "provider": "ngrok" if "ngrok" in normalized else payload["platform"],
+            "updated_at": time.time(),
+        },
+    )
+
+
+def _report_brain_url(public_url: str) -> None:
+    _publish_brain_presence(public_url, source="report_attempt")
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not executor_url:
+        return
+    if not _should_report_brain_url(public_url):
+        return
+    last_error: Exception | None = None
+    connect_timeout = max(1.0, float(os.getenv("BRAIN_REPORT_CONNECT_TIMEOUT_SEC", "4.0") or 4.0))
+    read_timeout = max(5.0, float(os.getenv("BRAIN_REPORT_READ_TIMEOUT_SEC", "15.0") or 15.0))
+    retries = max(1, int(os.getenv("BRAIN_REPORT_RETRIES", "2") or 2))
+    for _ in range(retries):
+        try:
+            response = requests.post(
+                f"{executor_url}/brain/report-url",
+                json={
+                    "brain_url": public_url,
+                    "platform": "kaggle" if _is_kaggle_runtime() else "remote",
+                    "role": os.getenv("BRAIN_PRIMARY_ROLE", "fallback"),
+                    "roles": [part.strip() for part in os.getenv("BRAIN_ROLES", "supervisor,chat,coding,planner,arabic,fallback").split(",") if part.strip()],
+                    "languages": [part.strip() for part in os.getenv("BRAIN_LANGUAGES", "ar,en").split(",") if part.strip()],
+                    "model_profile_id": os.getenv("MODEL_PROFILE_ID") or os.getenv("SUPERVISOR_MODEL_PROFILE_ID") or DEFAULT_MODEL_PROFILE_ID,
+                    "model_repo": MODEL_META.get("repo_id") or os.getenv("MODEL_REPO") or DEFAULT_MODEL_REPO,
+                    "model_file": MODEL_META.get("filename") or os.getenv("MODEL_FILE") or DEFAULT_MODEL_FILE,
+                },
+                headers=_brain_headers(),
+                timeout=(connect_timeout, read_timeout),
+            )
+            response.raise_for_status()
+            _publish_brain_presence(public_url, source="executor_report")
+            return
+        except Exception as exc:
+            last_error = exc
+            time.sleep(1)
+    logger.info(
+        "Brain URL report to executor timed out or failed; continuing (%s)",
+        last_error,
+    )
+
+
+def _pull_executor_settings() -> dict[str, Any]:
+    if _shared_state_backend() in {"google_drive", "drive", "gdrive"} or _drive_bootstrap_configured():
+        return {}
+    executor_url = _load_saved_executor_url()
+    if not executor_url:
+        return {}
+    try:
+        response = requests.get(
+            f"{executor_url}/share/settings",
+            headers=_brain_headers(),
+            timeout=(
+                max(1.5, float(os.getenv("EXECUTOR_CONNECT_TIMEOUT_SEC", "3.0") or 3.0)),
+                max(2.0, float(os.getenv("EXECUTOR_SETTINGS_READ_TIMEOUT_SEC", "5.0") or 5.0)),
+            ),
+        )
+        if response.status_code == 200:
+            return response.json()
+        logger.warning("Executor settings request failed: %s", response.text[:400])
+    except Exception as exc:
+        logger.warning("Failed to pull executor settings (%s)", exc)
+    return {}
+
+
+def start_ngrok(token: str | None = None) -> str | None:
+    restart_reuse = str(os.getenv("KAPO_RESTART_REUSE_PUBLIC_URL", "")).strip().lower() in {"1", "true", "yes", "on"}
+    if restart_reuse:
+        saved_public_url = _load_saved_public_url()
+        if saved_public_url:
+            _remember_public_url(saved_public_url)
+            _report_brain_url(saved_public_url)
+            FIREBASE.set_document("brains", saved_public_url, {"url": saved_public_url, "status": "healthy", "source": "restart_reuse"})
+            FIREBASE.set_document("tunnels", f"brain_{saved_public_url}", {"kind": "brain", "public_url": saved_public_url, "provider": "ngrok"})
+            logger.info("Reusing saved brain public URL after restart: %s", saved_public_url)
+            os.environ["KAPO_RESTART_REUSE_PUBLIC_URL"] = "0"
+            return saved_public_url
+
+    configured_public_url = _configured_public_url()
+    if configured_public_url and _prefer_configured_public_url():
+        _remember_public_url(configured_public_url)
+        _report_brain_url(configured_public_url)
+        FIREBASE.set_document("brains", configured_public_url, {"url": configured_public_url, "status": "healthy", "source": "configured_public_url"})
+        FIREBASE.set_document("tunnels", f"brain_{configured_public_url}", {"kind": "brain", "public_url": configured_public_url, "provider": "configured"})
+        logger.info("Using configured brain public URL without starting ngrok: %s", configured_public_url)
+        return configured_public_url
+
+    if not _ngrok_bootstrap_enabled():
+        logger.info("Skipping ngrok bootstrap because BRAIN_AUTO_NGROK is disabled")
+        return None
+
+    try:
+        authtoken = str(token or os.getenv("NGROK_AUTHTOKEN") or "").strip()
+        if not authtoken:
+            return None
+
+        port = int(os.getenv("BRAIN_PORT", "7860"))
+        api_url = _find_live_ngrok_api()
+        if not api_url:
+            api_url = _start_detached_ngrok_agent(authtoken)
+        if not api_url:
+            logger.warning("Ngrok agent did not expose a local API URL")
+            return None
+
+        public_url = _existing_ngrok_public_url(api_url, port)
+        if not public_url:
+            public_url = _create_ngrok_tunnel(api_url, port)
+        if not public_url:
+            return None
+
+        match = re.search(r"https://[A-Za-z0-9.-]+", public_url)
+        if match:
+            public_url = match.group(0)
+        _remember_ngrok_api_url(api_url)
+        _remember_public_url(public_url)
+        _report_brain_url(public_url)
+        FIREBASE.set_document("brains", public_url, {"url": public_url, "status": "healthy", "source": "ngrok_bootstrap"})
+        FIREBASE.set_document("tunnels", f"brain_{public_url}", {"kind": "brain", "public_url": public_url, "provider": "ngrok", "api_url": api_url})
+        return public_url
+    except Exception:
+        logger.exception("Ngrok startup failed")
+        return None
+
+
+def _report_known_public_url() -> str | None:
+    public_url = _load_saved_public_url()
+    if not public_url:
+        return None
+    _remember_public_url(public_url)
+    _report_brain_url(public_url)
+    FIREBASE.set_document("brains", public_url, {"url": public_url, "status": "healthy", "source": "saved_public_url"})
+    logger.info("Reported known brain public URL without starting ngrok: %s", public_url)
+    return public_url
+
+
+def _bootstrap_executor_handshake(start_tunnel: bool = False) -> None:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip()
+    if not executor_url:
+        if start_tunnel:
+            public_url = start_ngrok(os.getenv("NGROK_AUTHTOKEN") or None)
+            if public_url:
+                logger.info("Brain public URL started locally without executor handshake: %s", public_url)
+            else:
+                logger.info("Brain started without publishing a public URL")
+            return
+        logger.info("Skipping executor handshake: EXECUTOR_URL not configured")
+        return
+
+    settings = _pull_executor_settings()
+    _apply_executor_settings(settings)
+
+    public_url = None
+    if start_tunnel:
+        public_url = start_ngrok(os.getenv("NGROK_AUTHTOKEN") or None)
+        if not public_url:
+            public_url = _report_known_public_url()
+    else:
+        public_url = _report_known_public_url()
+    if public_url:
+        logger.info("Brain public URL reported to executor: %s", public_url)
+    else:
+        logger.info("Brain started without publishing a public URL")
+
+
+@app.on_event("startup")
+async def startup_event():
+    global RUNTIME_STATE_THREAD_STARTED
+    try:
+        _bootstrap_shared_state()
+    except Exception:
+        logger.exception("Shared-state bootstrap failed")
+    try:
+        _prepare_runtime_environment()
+    except Exception:
+        logger.exception("Runtime environment bootstrap failed")
+    try:
+        _run_startup_self_update()
+    except Exception:
+        logger.exception("Startup self-update bootstrap failed")
+    internal_restart = _internal_restart_in_progress()
+    fast_restart = internal_restart and _fast_restart_enabled()
+    if not fast_restart:
+        try:
+            settings = _pull_executor_settings()
+            _apply_executor_settings(settings)
+        except Exception:
+            logger.exception("Executor settings bootstrap failed")
+        try:
+            _apply_firebase_runtime_settings()
+        except Exception:
+            logger.exception("Firebase runtime bootstrap failed")
+    else:
+        logger.info("Fast internal restart enabled; skipping executor/Firebase startup bootstrap")
+    if not fast_restart:
+        _load_default_model()
+    try:
+        if not fast_restart:
+            _load_embed_model()
+    except Exception:
+        logger.exception("Embedding model startup failed")
+    try:
+        start_tunnel = _auto_publish_public_url_on_startup() and not internal_restart
+        _bootstrap_executor_handshake(start_tunnel=start_tunnel)
+    except Exception:
+        logger.exception("Executor handshake startup failed")
+    finally:
+        os.environ["KAPO_INTERNAL_RESTART"] = "0"
+    _persist_runtime_state_snapshot(reason="startup")
+    if not RUNTIME_STATE_THREAD_STARTED:
+        RUNTIME_STATE_THREAD_STARTED = True
+        threading.Thread(target=_runtime_state_pulse, daemon=True).start()
+
+
+class ModelLoadRequest(BaseModel):
+    repo_id: str
+    filename: str
+    hf_token: str | None = None
+
+
+class ConnectionInit(BaseModel):
+    executor_url: str
+    ngrok_token: str | None = None
+
+
+class PublishUrlRequest(BaseModel):
+    ngrok_token: str | None = None
+    public_url: str | None = None
+    start_tunnel: bool = True
+
+
+class RestartRequest(BaseModel):
+    delay_sec: float = 1.0
+
+
+class FileWriteRequest(BaseModel):
+    path: str
+    content: str = ""
+    overwrite: bool = True
+
+
+class FileDeleteRequest(BaseModel):
+    path: str
+    recursive: bool = False
+
+
+class FileMkdirRequest(BaseModel):
+    path: str
+
+
+class ChatRequest(BaseModel):
+    request_id: str
+    user_input: str
+    context: dict[str, Any] = {}
+    history: list[dict[str, str]] = []
+    auto_execute: bool = True
+
+
+def _contains_arabic(text: str) -> bool:
+    return bool(re.search(r"[\u0600-\u06FF]", text or ""))
+
+
+def _detect_language(text: str) -> str:
+    return "ar" if _contains_arabic(text) else "en"
+
+
+def _is_task_request(text: str) -> bool:
+    lower = (text or "").strip().lower()
+    task_words = [
+        "build", "fix", "debug", "create project", "generate project", "implement", "refactor",
+        "run", "execute", "install", "modify", "edit", "update", "write code", "make app",
+        "انشئ", "أنشئ", "اعمل", "نفذ", "شغل", "اصلح", "أصلح", "عدّل", "عدل", "ابني", "كوّن مشروع",
+    ]
+    return any(word in lower for word in task_words)
+
+
+def _is_research_request(text: str) -> bool:
+    lower = (text or "").strip().lower()
+    research_words = [
+        "search", "research", "look up", "find out", "web", "browse",
+        "ابحث", "ابحث عن", "دور", "فتش", "معلومة عن", "معلومات عن",
+    ]
+    return any(word in lower for word in research_words)
+
+
+def _is_knowledge_request(text: str, context: dict[str, Any] | None = None) -> bool:
+    context = context or {}
+    if bool(context.get("use_executor_knowledge")):
+        return True
+    lower = (text or "").strip().lower()
+    knowledge_words = [
+        "remember", "memory", "knowledge", "docs", "documentation", "project structure", "architecture",
+        "تذكر", "الذاكرة", "المعرفة", "الوثائق", "الدليل", "بنية المشروع", "هيكل المشروع", "معمارية",
+    ]
+    return any(word in lower for word in knowledge_words)
+
+
+def _prune_history(history: list[dict[str, str]], keep_last: int = 6) -> list[dict[str, str]]:
+    if len(history) <= keep_last:
+        return history
+    return history[-keep_last:]
+
+
+def _retrieve_knowledge(query: str, top_k: int = 4) -> list[dict[str, Any]]:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    expanded_query = _expand_project_query(query)
+    if _executor_roundtrip_allowed("BRAIN_REMOTE_KNOWLEDGE_ENABLED", default=True):
+        try:
+            response = requests.get(
+                f"{executor_url}/rag/search",
+                params={"query": expanded_query, "top_k": top_k},
+                headers=_brain_headers(),
+                timeout=(
+                    _executor_connect_timeout(),
+                    _executor_read_timeout("BRAIN_REMOTE_KNOWLEDGE_TIMEOUT_SEC", 6.0),
+                ),
+            )
+            if response.status_code == 200:
+                payload = response.json()
+                results = payload.get("results", [])
+                if isinstance(results, list):
+                    return results
+        except requests.exceptions.ReadTimeout:
+            logger.info("Executor knowledge retrieval timed out; continuing without remote knowledge")
+        except Exception:
+            logger.warning("Executor knowledge retrieval failed", exc_info=True)
+    if _remote_brain_only() or not _feature_enabled("BRAIN_LOCAL_RAG_FALLBACK_ENABLED", default=False):
+        return []
+    try:
+        from rag.retriever import retrieve
+
+        return retrieve(expanded_query, top_k=top_k)
+    except Exception:
+        logger.warning("Knowledge retrieval failed", exc_info=True)
+        return []
+
+
+def _search_web(query: str) -> list[dict[str, Any]]:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not _executor_roundtrip_allowed("BRAIN_REMOTE_WEB_SEARCH_ENABLED", default=True):
+        return []
+    try:
+        response = requests.post(
+            f"{executor_url}/tools/search",
+            json={"query": query, "num_results": 5},
+            headers=_brain_headers(),
+            timeout=(
+                _executor_connect_timeout(),
+                _executor_read_timeout("BRAIN_REMOTE_WEB_SEARCH_TIMEOUT_SEC", 8.0),
+            ),
+        )
+        if response.status_code == 200:
+            payload = response.json()
+            results = payload.get("results", [])
+            return results if isinstance(results, list) else []
+    except Exception:
+        logger.warning("Web search failed", exc_info=True)
+    return []
+
+
+def _format_context_blocks(knowledge: list[dict[str, Any]], web_results: list[dict[str, Any]]) -> str:
+    blocks: list[str] = []
+    if knowledge:
+        lines = []
+        for item in knowledge[:4]:
+            source = item.get("source", "knowledge")
+            content = item.get("content", "") or item.get("text", "")
+            lines.append(f"- [{source}] {content[:500]}")
+        blocks.append("Knowledge:\n" + "\n".join(lines))
+    if web_results:
+        lines = []
+        for item in web_results[:5]:
+            lines.append(f"- {item.get('title', '')}: {item.get('snippet', '')}")
+        blocks.append("Web:\n" + "\n".join(lines))
+    return "\n\n".join(blocks).strip()
+
+
+def _project_context_tags(text: str) -> list[str]:
+    source = str(text or "")
+    lowered = source.lower()
+    tags: list[str] = []
+    tag_rules = [
+        ("brain_runtime", ["العقل", "brain", "model", "موديل", "النموذج"]),
+        ("executor_runtime", ["الوكيل التنفيذي", "executor", "agent"]),
+        ("tunnel_runtime", ["النفق", "tunnel", "ngrok", "cloudflare"]),
+        ("url_routing", ["الرابط", "url", "endpoint", "لينك"]),
+        ("restart_sync", ["restart", "ريستارت", "إعادة تشغيل", "اعادة تشغيل", "sync", "مزامنة"]),
+        ("knowledge_memory", ["memory", "ذاكرة", "معرفة", "knowledge", "rag", "طبقات", "embedding", "embeddings"]),
+        ("kaggle_runtime", ["kaggle", "كاجل"]),
+    ]
+    for tag, markers in tag_rules:
+        if any(marker in source or marker in lowered for marker in markers):
+            tags.append(tag)
+    return tags
+
+
+def _expand_project_query(query: str) -> str:
+    tags = _project_context_tags(query)
+    additions: list[str] = []
+    if "tunnel_runtime" in tags:
+        additions.append("ngrok tunnel public url reverse proxy runtime restart")
+    if "restart_sync" in tags:
+        additions.append("system restart sync uvicorn process reuse public url")
+    if "executor_runtime" in tags:
+        additions.append("executor share settings control plane local machine")
+    if "knowledge_memory" in tags:
+        additions.append("knowledge layers rag embeddings preferences profile")
+    if "brain_runtime" in tags:
+        additions.append("brain server kaggle model startup runtime")
+    return query if not additions else f"{query}\nContext expansion: {' | '.join(additions)}"
+
+
+def _fetch_style_profile() -> dict[str, Any]:
+    firebase_profile = FIREBASE.get_document("profiles", "style", ttl_sec=30.0)
+    if firebase_profile:
+        return firebase_profile
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not executor_url or not _executor_roundtrip_allowed("BRAIN_REMOTE_STYLE_PROFILE_ENABLED", default=False):
+        return {}
+    try:
+        response = requests.get(
+            f"{executor_url}/preferences/profile",
+            headers=_brain_headers(),
+            timeout=(
+                _executor_connect_timeout(),
+                _executor_read_timeout("BRAIN_REMOTE_STYLE_PROFILE_TIMEOUT_SEC", 2.5),
+            ),
+        )
+        if response.status_code != 200:
+            return {}
+        payload = response.json().get("profile", {})
+        return payload if isinstance(payload, dict) else {}
+    except requests.exceptions.ReadTimeout:
+        logger.info("Style profile load timed out; continuing without remote style profile")
+        return {}
+    except Exception:
+        logger.warning("Failed to load style profile", exc_info=True)
+        return {}
+
+
+def _render_style_profile_context(profile: dict[str, Any]) -> str:
+    if not profile:
+        return ""
+    preferences = profile.get("preferences", []) or []
+    examples = profile.get("examples", []) or []
+    lexical_signals = profile.get("lexical_signals", []) or []
+    style_markers = profile.get("style_markers", {}) or {}
+    persona_summary = str(profile.get("persona_summary") or "").strip()
+    response_contract = str(profile.get("response_contract") or "").strip()
+    lines: list[str] = []
+    if persona_summary:
+        lines.append(f"User persona summary: {persona_summary}")
+    if response_contract:
+        lines.append(f"Response contract: {response_contract}")
+    if preferences:
+        lines.append("User Style Preferences:")
+        for item in preferences[:10]:
+            lines.append(f"- {item}")
+    if lexical_signals:
+        lines.append("User Lexical Signals:")
+        for item in lexical_signals[:10]:
+            lines.append(f"- {item}")
+    if style_markers:
+        lines.append("Style Markers:")
+        for key, value in sorted(style_markers.items()):
+            lines.append(f"- {key}: {value}")
+    if examples:
+        lines.append("Recent User Style Examples:")
+        for sample in examples[-3:]:
+            user_text = str(sample.get("user_input") or "").strip()
+            assistant_text = str(sample.get("assistant_reply") or "").strip()
+            if user_text:
+                lines.append(f"- User: {user_text}")
+            if assistant_text:
+                lines.append(f"  Assistant: {assistant_text}")
+    return "\n".join(lines).strip()
+
+
+def _project_domain_context(user_input: str, context: dict[str, Any] | None = None) -> str:
+    tags = _project_context_tags(user_input)
+    if not tags:
+        return ""
+    lines = [
+        "Project Domain Glossary:",
+        "- In this project, terms like العقل, الوكيل التنفيذي, النفق, الرابط, الريستارت, المزامنة, الذاكرة, والطبقات usually refer to software runtime and operations concepts.",
+        "- Treat النفق as ngrok or cloudflare tunnel unless the user explicitly asks for a literal/civil meaning.",
+        "- Treat الرابط as public URL, endpoint, or routing target when the surrounding context mentions deployment, Kaggle, restart, or sync.",
+        "- Treat العقل as the remote Brain service/model runtime, and الوكيل التنفيذي as the local executor/control plane on the user's device.",
+    ]
+    if "restart_sync" in tags:
+        lines.append("- Restart means process/service restart; preserving the same public URL matters more than creating a fresh tunnel.")
+    if "knowledge_memory" in tags:
+        lines.append("- Knowledge, embeddings, layers, and memory refer to the RAG and memory system inside this project.")
+    if "kaggle_runtime" in tags:
+        lines.append("- Kaggle here is the remote runtime hosting the Brain service.")
+    role_name = str((context or {}).get("role_name") or "").strip()
+    if role_name:
+        lines.append(f"- Current assigned role: {role_name}.")
+    return "\n".join(lines)
+
+
+def _firebase_runtime_context(role_name: str, language: str) -> str:
+    snapshot = _firebase_runtime_snapshot()
+    lines: list[str] = []
+    roles = snapshot.get("roles") or []
+    if roles:
+        enabled_roles = [
+            str(item.get("name") or item.get("id") or "").strip()
+            for item in roles
+            if str(item.get("enabled", True)).strip().lower() not in {"0", "false", "no", "off"}
+        ]
+        enabled_roles = [item for item in enabled_roles if item]
+        if enabled_roles:
+            lines.append("Live roles from Firestore: " + ", ".join(enabled_roles[:12]))
+    models = snapshot.get("models") or []
+    if models:
+        preferred = [
+            item for item in models
+            if str(item.get("enabled", True)).strip().lower() not in {"0", "false", "no", "off"}
+        ]
+        if preferred:
+            labels = [str(item.get("label") or item.get("id") or "").strip() for item in preferred[:5]]
+            labels = [item for item in labels if item]
+            if labels:
+                lines.append("Live model profiles: " + ", ".join(labels))
+    platforms = snapshot.get("platforms") or []
+    if platforms:
+        names = [str(item.get("name") or "").strip() for item in platforms[:6] if str(item.get("name") or "").strip()]
+        if names:
+            lines.append("Live platforms: " + ", ".join(names))
+    prompt_body = _firebase_prompt_body(role_name or "chat", language) or _firebase_prompt_body(role_name or "chat", "en")
+    if prompt_body:
+        lines.append(f"Live Firestore prompt for role '{role_name or 'chat'}': {prompt_body}")
+    return "\n".join(lines).strip()
+
+
+def _append_runtime_instructions(context_block: str, context: dict[str, Any]) -> str:
+    instructions = str((context or {}).get("system_instructions") or "").strip()
+    role_name = str((context or {}).get("role_name") or "").strip()
+    user_input = str((context or {}).get("user_input") or "").strip()
+    language = _detect_language(user_input)
+    style_profile = _render_style_profile_context(_fetch_style_profile())
+    domain_context = _project_domain_context(user_input, context)
+    firebase_context = _firebase_runtime_context(role_name, language)
+    if not instructions and not role_name and not style_profile and not domain_context and not firebase_context:
+        return context_block
+    extra = []
+    if role_name:
+        extra.append(f"Assigned role: {role_name}")
+    if instructions:
+        extra.append(instructions)
+    if firebase_context:
+        extra.append(firebase_context)
+    if style_profile:
+        extra.append(style_profile)
+    if domain_context:
+        extra.append(domain_context)
+    extra_block = "Runtime Instructions:\n" + "\n".join(extra)
+    return (context_block + "\n\n" + extra_block).strip() if context_block else extra_block
+
+
+def _extract_exact_reply_instruction(user_input: str) -> str:
+    text = (user_input or "").strip()
+    patterns = [
+        r'(?is)reply\s+with\s+exactly\s+[:"]?\s*(.+?)\s*[".]?$',
+        r'(?is)respond\s+with\s+exactly\s+[:"]?\s*(.+?)\s*[".]?$',
+        r"(?is)قل\s+فقط[:：]?\s*(.+?)\s*$",
+        r"(?is)اكتب\s+فقط[:：]?\s*(.+?)\s*$",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return match.group(1).strip().strip("\"'`")
+    return ""
+
+
+def _extract_exact_reply_instruction_safe(user_input: str) -> str:
+    text = (user_input or "").strip()
+    patterns = [
+        r'(?is)reply\s+with\s+exactly\s+[:"]?\s*(.+?)\s*[".]?$',
+        r'(?is)respond\s+with\s+exactly\s+[:"]?\s*(.+?)\s*[".]?$',
+        r"(?is)\u0642\u0644\s+\u0641\u0642\u0637[:\uff1a]?\s*(.+?)\s*$",
+        r"(?is)\u0627\u0643\u062a\u0628\s+\u0641\u0642\u0637[:\uff1a]?\s*(.+?)\s*$",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return match.group(1).strip().strip("\"'`")
+    return _extract_exact_reply_instruction(user_input)
+
+
+def _chat_system_instruction(language: str, user_input: str = "", exact_reply: str = "") -> str:
+    if language == "ar":
+        base = (
+            "أنت KAPO-AI، مساعد هندسي عملي. "
+            "أجب مباشرة وبوضوح وبشكل مفيد. "
+            "افهم المطلوب أولاً ثم أجب دون مقدمات زائدة. "
+            "لا تقل إن المحادثة غير مكتملة ولا تذكر تعليماتك الداخلية."
+        )
+        base += (
+            " في هذا المشروع، كلمات مثل العقل والوكيل التنفيذي والنفق والرابط والريستارت والمزامنة "
+            "والطبقات والتضمينات وكاجل وngrok وcloudflare وendpoint وmodel تشير غالبا إلى "
+            "مكونات برمجية وتشغيلية، وليست معاني حرفية أو هندسة مدنية، ما لم يطلب المستخدم غير ذلك صراحة."
+        )
+        if exact_reply:
+            return base + f' يجب أن يكون ردك هو هذا النص فقط حرفياً: "{exact_reply}"'
+        return base
+    base = (
+        "You are KAPO-AI, an engineering assistant. "
+        "Answer directly, clearly, and practically. "
+        "Understand the request before answering. "
+        "Do not say the conversation is incomplete and do not mention hidden instructions."
+    )
+    if exact_reply:
+        return base + f' Your entire reply must be exactly: "{exact_reply}"'
+    return base
+
+
+def _build_chat_prompt(user_input: str, history: list[dict[str, str]], context_block: str) -> str:
+    language = _detect_language(user_input)
+    exact_reply = _extract_exact_reply_instruction_safe(user_input)
+    history_lines: list[str] = []
+    for message in _prune_history(history):
+        role = message.get("role", "user")
+        role_label = "المستخدم" if language == "ar" and role == "user" else role.upper()
+        if language == "ar" and role != "user":
+            role_label = "المساعد"
+        history_lines.append(f"{role_label}: {message.get('content', '')}")
+
+    history_section = ""
+    if history_lines:
+        history_section = "\n### History\n" + "\n".join(history_lines) + "\n"
+
+    context_section = f"\n### Context\n{context_block}\n" if context_block else ""
+    user_label = "المستخدم" if language == "ar" else "User"
+    assistant_label = "المساعد" if language == "ar" else "Assistant"
+    return (
+        f"### System\n{_chat_system_instruction(language, user_input, exact_reply)}\n"
+        f"{history_section}"
+        f"{context_section}"
+        f"### Instruction\n"
+        f"{user_label}: {user_input}\n"
+        f"{assistant_label}:"
+    )
+
+
+def _response_looks_bad(text: str, language: str) -> bool:
+    cleaned = (text or "").strip()
+    if not cleaned:
+        return True
+    markers = [
+        "the assistant is not sure",
+        "conversation seems incomplete",
+        "provide more information",
+        "unless otherwise noted",
+        "as an ai model developed by",
+        "developed by ibm",
+        "tensorflow library",
+        "dataset of 1024",
+    ]
+    if any(marker in cleaned.lower() for marker in markers):
+        return True
+    if language == "ar":
+        arabic_chars = len(re.findall(r"[\u0600-\u06FF]", cleaned))
+        latin_chars = len(re.findall(r"[A-Za-z]", cleaned))
+        if arabic_chars < 8 and latin_chars > max(12, arabic_chars * 2):
+            return True
+    return False
+
+
+def _fallback_response(user_input: str) -> str:
+    if _detect_language(user_input) == "ar":
+        return "فهمت رسالتك، لكن الرد المولد لم يكن صالحاً للاستخدام. أعد صياغة الطلب بشكل أكثر تحديداً."
+    return "I understood your message, but the generated reply was not usable. Please rephrase the request more specifically."
+
+
+def _project_specific_fast_reply(user_input: str) -> str:
+    text = (user_input or "").strip()
+    lower = text.lower()
+    if any(token in text for token in ("ايه اللي اتصلح", "إيه اللي اتصلح", "هو ايه اللي اتصلح", "هو إيه اللي اتصلح")) and any(
+        token in text or token in lower for token in ("النفق", "الرابط", "الريستارت", "restart")
+    ):
+        return (
+            "الذي اتصلح هو أن الريستارت الداخلي بقى يعيد تشغيل خدمة العقل نفسها من غير ما يكسر النفق أو يغيّر الرابط العام. "
+            "ولو ظهر توقف قصير أثناء الإقلاع فهذا يكون من رجوع الخدمة، لا من إنشاء نفق جديد."
+        )
+    if "النفق" in text and any(token in text for token in ("إصلاح", "اصلاح", "الذي تم", "اتصلح", "تم إصلاح", "تم اصلاح")):
+        return (
+            "تم فصل دورة حياة النفق عن دورة حياة خدمة العقل، فأصبح ngrok يعمل كعامل مستقل عن عملية Uvicorn. "
+            "وبالتالي يحتفظ /system/restart بنفس الرابط العام بدل إنشاء رابط جديد، وقد يظهر ERR_NGROK_8012 مؤقتًا فقط أثناء الإقلاع."
+        )
+    if "نفس الرابط" in text and ("ريستارت" in text or "restart" in lower):
+        return (
+            "الهدف هنا أن تعيد الخدمة الإقلاع داخليًا مع الإبقاء على نفس الـ public URL. "
+            "لذلك يبقى tunnel حيًا، بينما تعود خدمة localhost:7860 للعمل بعد ثوانٍ قليلة على نفس الرابط."
+        )
+    return ""
+
+
+def _generate_response(user_input: str, history: list[dict[str, str]], context_block: str) -> str:
+    language = _detect_language(user_input)
+    exact_reply = _extract_exact_reply_instruction_safe(user_input)
+    if exact_reply:
+        return exact_reply
+    fast_reply = _project_specific_fast_reply(user_input)
+    if fast_reply:
+        return fast_reply
+    if MODEL is None:
+        if language == "ar":
+            return "الخدمة تعمل لكن توليد الرد الحر غير متاح الآن لأن النموذج غير محمل."
+        return "The Brain is online, but natural chat generation is unavailable because the model is not loaded."
+
+    prompt = _build_chat_prompt(user_input, history, context_block)
+
+    try:
+        max_tokens = 80 if language == "ar" else 96
+        output = MODEL(
+            prompt,
+            max_tokens=max_tokens,
+            temperature=0.1,
+            top_p=0.85,
+            stop=["\nUser:", "\nUSER:", "\nالمستخدم:", "\n###", "<|EOT|>"],
+        )
+        text = output["choices"][0]["text"].strip()
+        if _response_looks_bad(text, language):
+            return _fallback_response(user_input)
+        return text or ("تم استلام رسالتك." if language == "ar" else "I received your message.")
+    except Exception:
+        logger.exception("Model generation failed")
+        if language == "ar":
+            return "فهمت طلبك، لكن فشل توليد الرد النصي."
+        return "I understood your request, but text generation failed."
+
+
+def _store_chat_trace(request_id: str, payload: dict[str, Any]) -> None:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not _executor_roundtrip_allowed("BRAIN_REMOTE_TRACE_STORE_ENABLED", default=True):
+        return
+    try:
+        requests.post(
+            f"{executor_url}/memory/store",
+            json={"request_id": request_id, "payload": payload},
+            headers=_brain_headers(),
+            timeout=(
+                _executor_connect_timeout(),
+                _executor_read_timeout("BRAIN_REMOTE_TRACE_STORE_TIMEOUT_SEC", 2.5),
+            ),
+        )
+    except requests.exceptions.ReadTimeout:
+        logger.info("Chat trace store timed out; continuing")
+    except Exception:
+        logger.warning("Failed to store chat trace on executor", exc_info=True)
+
+
+def _ingest_chat_knowledge(request_id: str, user_input: str, reply: str) -> None:
+    if len(reply or "") < 180:
+        return
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not _executor_roundtrip_allowed("BRAIN_REMOTE_AUTO_INGEST_ENABLED", default=False):
+        return
+    payload = {
+        "request_id": request_id,
+        "payload": {
+            "source": "auto_chat",
+            "content": f"User: {user_input}\nAssistant: {reply}",
+        },
+    }
+    try:
+        requests.post(
+            f"{executor_url}/rag/ingest",
+            json=payload,
+            headers=_brain_headers(),
+            timeout=(
+                _executor_connect_timeout(),
+                _executor_read_timeout("BRAIN_REMOTE_AUTO_INGEST_TIMEOUT_SEC", 3.0),
+            ),
+        )
+    except requests.exceptions.ReadTimeout:
+        logger.info("Auto-ingest chat knowledge timed out; continuing")
+    except Exception:
+        logger.warning("Failed to auto-ingest chat knowledge", exc_info=True)
+
+
+def _learn_user_style(request_id: str, user_input: str, reply: str, context: dict[str, Any]) -> None:
+    executor_url = os.getenv("EXECUTOR_URL", "").strip().rstrip("/")
+    if not executor_url or not _executor_roundtrip_allowed("BRAIN_REMOTE_STYLE_PROFILE_ENABLED", default=False):
+        return
+    try:
+        requests.post(
+            f"{executor_url}/preferences/learn",
+            json={
+                "request_id": request_id,
+                "user_input": user_input,
+                "assistant_reply": reply,
+                "context": context or {},
+            },
+            headers=_brain_headers(),
+            timeout=(
+                _executor_connect_timeout(),
+                _executor_read_timeout("BRAIN_REMOTE_TRACE_STORE_TIMEOUT_SEC", 2.5),
+            ),
+        )
+    except requests.exceptions.ReadTimeout:
+        logger.info("Style learning timed out; continuing")
+    except Exception:
+        logger.warning("Failed to learn user style on executor", exc_info=True)
+
+
+def _dispatch_background(task, *args) -> None:
+    try:
+        threading.Thread(target=task, args=args, daemon=True).start()
+    except Exception:
+        logger.warning("Background task dispatch failed", exc_info=True)
+
+
+def _restart_process(delay_sec: float = 1.0) -> None:
+    if _is_hf_space_runtime():
+        logger.info("Skipping in-process restart on Hugging Face Space runtime")
+        return
+    def _run() -> None:
+        time.sleep(max(0.2, float(delay_sec)))
+        target_root = _sync_target_root()
+        os.chdir(target_root)
+        os.environ["KAPO_INTERNAL_RESTART"] = "1"
+        os.environ.setdefault("KAPO_FAST_INTERNAL_RESTART", "1")
+        if _reuse_public_url_on_restart():
+            current_public_url = _load_saved_public_url()
+            if current_public_url:
+                _remember_public_url(current_public_url)
+                os.environ["KAPO_RESTART_REUSE_PUBLIC_URL"] = "1"
+        port = str(os.getenv("BRAIN_PORT", "7860") or "7860")
+        app_module = str(os.getenv("KAPO_UVICORN_APP") or "").strip()
+        if not app_module:
+            if (Path(target_root) / "brain_server" / "api" / "main.py").exists():
+                app_module = "brain_server.api.main:app"
+            elif (Path(target_root) / "api" / "main.py").exists():
+                app_module = "api.main:app"
+            else:
+                app_module = "brain_server.api.main:app"
+        os.execv(
+            sys.executable,
+            [
+                sys.executable,
+                "-m",
+                "uvicorn",
+                app_module,
+                "--host",
+                "0.0.0.0",
+                "--port",
+                port,
+            ],
+        )
+
+    threading.Thread(target=_run, daemon=True).start()
+
+
+@app.get("/")
+async def root():
+    return {"status": "ok", "service": "brain_server", "docs": "/docs", "health": "/health"}
+
+
+@app.get("/runtime/firebase")
+async def runtime_firebase_snapshot():
+    try:
+        return {"status": "ok", "firebase": _json_safe(_firebase_runtime_snapshot())}
+    except Exception as exc:
+        logger.warning("Failed to build firebase runtime snapshot", exc_info=True)
+        return {"status": "degraded", "firebase": {"platforms": [], "models": [], "prompts": [], "roles": []}, "detail": str(exc)}
+
+
+@app.get("/runtime/errors")
+async def runtime_errors(limit: int = 50, level: str = "WARNING"):
+    normalized = str(level or "WARNING").strip().upper()
+    allowed = {"DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50}
+    threshold = allowed.get(normalized, 30)
+    items = [item for item in list(RUNTIME_LOG_BUFFER) if allowed.get(str(item.get("level") or "").upper(), 0) >= threshold]
+    return {"status": "ok", "count": len(items[-limit:]), "items": items[-limit:]}
+
+
+@app.get("/runtime/modernization")
+async def runtime_modernization():
+    try:
+        return {"status": "ok", "modernization": _runtime_modernization_snapshot()}
+    except Exception as exc:
+        logger.warning("Failed to build runtime modernization snapshot", exc_info=True)
+        return {"status": "degraded", "detail": str(exc), "modernization": {}}
+
+
+@app.get("/model/status")
+async def model_status():
+    return {
+        "loaded": MODEL is not None,
+        "error": MODEL_ERROR,
+        "repo_id": MODEL_META.get("repo_id"),
+        "filename": MODEL_META.get("filename"),
+    }
+
+
+@app.post("/model/load")
+async def model_load(req: ModelLoadRequest):
+    ensure_model_loaded(req.repo_id, req.filename, hf_token=req.hf_token)
+    return await model_status()
+
+
+@app.post("/model/hotswap")
+async def model_hotswap(req: ModelLoadRequest):
+    global MODEL
+    if MODEL is not None:
+        del MODEL
+        gc.collect()
+        MODEL = None
+    ensure_model_loaded(req.repo_id, req.filename, hf_token=req.hf_token)
+    return await model_status()
+
+
+@app.post("/embeddings")
+async def embeddings(payload: dict[str, Any]):
+    if EMBED_MODEL is None:
+        _load_embed_model()
+    texts = payload.get("texts") or []
+    if not texts:
+        return {"embeddings": []}
+    return {"embeddings": EMBED_MODEL.encode(texts).tolist()}
+
+
+@app.post("/chat")
+async def chat(req: ChatRequest):
+    try:
+        exact_reply = _extract_exact_reply_instruction_safe(req.user_input)
+        if exact_reply:
+            runtime_context = {**(req.context or {}), "user_input": req.user_input}
+            trace_payload = {
+                "mode": "chat",
+                "user_input": req.user_input,
+                "reply": exact_reply,
+                "plan": None,
+                "execution": None,
+                "knowledge": [],
+                "web_results": [],
+                "context": runtime_context,
+            }
+            memory = MemoryAgent()
+            memory.write_short_term(req.request_id, trace_payload)
+            return {
+                "status": "ok",
+                "mode": "chat",
+                "reply": exact_reply,
+                "plan": None,
+                "rationale": None,
+                "execution": None,
+                "knowledge": [],
+                "web_results": [],
+                "timestamp": time.time(),
+            }
+
+        planner = PlannerAgent()
+        reasoning = ReasoningAgent()
+        memory = MemoryAgent()
+
+        mode = "task" if _is_task_request(req.user_input) else "chat"
+        runtime_context = {**(req.context or {}), "user_input": req.user_input}
+        knowledge = _retrieve_knowledge(req.user_input, top_k=4) if _is_knowledge_request(req.user_input, req.context) else []
+        web_results = _search_web(req.user_input) if _is_research_request(req.user_input) else []
+        context_block = _append_runtime_instructions(_format_context_blocks(knowledge, web_results), runtime_context)
+        response_text = ""
+        plan_steps = None
+        execution = None
+        rationale = None
+
+        if mode == "task":
+            plan_steps = planner.run(req.user_input, req.context)
+            rationale = reasoning.run(req.user_input, plan_steps)
+            response_text = (
+                "سأتعامل مع هذه الرسالة كطلب تنفيذ، وقمت ببناء خطة مبدئية وسأبدأ التنفيذ تلقائياً."
+                if _contains_arabic(req.user_input)
+                else "I treated this as an execution request, built a plan, and started automatic execution."
+            )
+            if req.auto_execute:
+                from api.routes_execute import ExecuteRequest, execute as execute_route
+
+                execution = await execute_route(
+                    ExecuteRequest(
+                        request_id=req.request_id,
+                        plan={"steps": plan_steps},
+                        executor_url=os.getenv("EXECUTOR_URL", "").strip() or None,
+                    )
+                )
+                if execution.get("report", {}).get("success"):
+                    response_text += (
+                        "\n\nتم التنفيذ بنجاح مبدئياً."
+                        if _contains_arabic(req.user_input)
+                        else "\n\nExecution completed successfully."
+                    )
+                else:
+                    response_text += (
+                        "\n\nتمت المحاولة لكن توجد مخرجات تحتاج مراجعة."
+                        if _contains_arabic(req.user_input)
+                        else "\n\nExecution ran, but the result still needs review."
+                    )
+        else:
+            response_text = _generate_response(req.user_input, req.history, context_block)
+
+        trace_payload = {
+            "mode": mode,
+            "user_input": req.user_input,
+            "reply": response_text,
+            "plan": plan_steps,
+            "execution": execution,
+            "knowledge": knowledge,
+            "web_results": web_results,
+            "context": runtime_context,
+        }
+        memory.write_short_term(req.request_id, trace_payload)
+        _dispatch_background(_store_chat_trace, req.request_id, trace_payload)
+        _dispatch_background(_ingest_chat_knowledge, req.request_id, req.user_input, response_text)
+        _dispatch_background(_learn_user_style, req.request_id, req.user_input, response_text, runtime_context)
+
+        return {
+            "status": "ok",
+            "mode": mode,
+            "reply": response_text,
+            "plan": plan_steps,
+            "rationale": rationale,
+            "execution": execution,
+            "knowledge": knowledge,
+            "web_results": web_results,
+            "timestamp": time.time(),
+        }
+    except Exception as exc:
+        logger.exception("Chat failed")
+        return {
+            "status": "error",
+            "mode": "chat",
+            "reply": "حدث خطأ أثناء معالجة الرسالة." if _contains_arabic(req.user_input) else "Chat processing failed.",
+            "detail": str(exc),
+            "timestamp": time.time(),
+        }
+
+
+@app.post("/init-connection")
+async def init_connection(payload: ConnectionInit):
+    _remember_executor_url(payload.executor_url)
+    FIREBASE.set_document("runtime", "executor", {"executor_url": payload.executor_url})
+    public_url = _report_known_public_url()
+    if not public_url:
+        public_url = start_ngrok(payload.ngrok_token)
+    return {"status": "connected", "brain_public_url": public_url}
+
+
+@app.post("/system/publish-url")
+async def system_publish_url(req: PublishUrlRequest | None = None):
+    payload = req or PublishUrlRequest()
+    explicit_public_url = str(payload.public_url or "").strip().rstrip("/")
+    if explicit_public_url:
+        _remember_public_url(explicit_public_url)
+        _report_brain_url(explicit_public_url)
+        FIREBASE.set_document("brains", explicit_public_url, {"url": explicit_public_url, "status": "healthy", "source": "explicit_publish"})
+        return {"status": "published", "brain_public_url": explicit_public_url, "mode": "explicit"}
+
+    if not payload.start_tunnel:
+        public_url = _report_known_public_url()
+        if public_url:
+            return {"status": "published", "brain_public_url": public_url, "mode": "saved"}
+        return {"status": "skipped", "brain_public_url": None, "mode": "none"}
+
+    public_url = start_ngrok(payload.ngrok_token)
+    if public_url:
+        return {"status": "published", "brain_public_url": public_url, "mode": "ngrok"}
+    public_url = _report_known_public_url()
+    return {"status": "published" if public_url else "error", "brain_public_url": public_url, "mode": "saved" if public_url else "none"}
+
+
+@app.get("/system/files")
+async def system_files(path: str = "", include_content: bool = False):
+    try:
+        target = _resolve_sync_path(path)
+        if not target.exists():
+            return {"status": "error", "detail": "Path not found", "path": path}
+        if target.is_file():
+            payload = {"status": "ok", "entry": _describe_sync_entry(target)}
+            if include_content:
+                payload["content"] = target.read_text(encoding="utf-8", errors="ignore")
+            return payload
+        items = sorted((_describe_sync_entry(item) for item in target.iterdir()), key=lambda item: (not item["is_dir"], item["name"].lower()))
+        return {"status": "ok", "root": str(_sync_root_path()), "path": path, "items": items}
+    except Exception as exc:
+        logger.exception("File listing failed")
+        return {"status": "error", "detail": str(exc), "path": path}
+
+
+@app.post("/system/files/write")
+async def system_files_write(payload: FileWriteRequest):
+    try:
+        target = _resolve_sync_path(payload.path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists() and target.is_dir():
+            return {"status": "error", "detail": "Target path is a directory"}
+        if target.exists() and not payload.overwrite:
+            return {"status": "error", "detail": "File already exists"}
+        target.write_text(payload.content or "", encoding="utf-8")
+        return {"status": "saved", "entry": _describe_sync_entry(target)}
+    except Exception as exc:
+        logger.exception("File write failed")
+        return {"status": "error", "detail": str(exc), "path": payload.path}
+
+
+@app.post("/system/files/mkdir")
+async def system_files_mkdir(payload: FileMkdirRequest):
+    try:
+        target = _resolve_sync_path(payload.path)
+        target.mkdir(parents=True, exist_ok=True)
+        return {"status": "created", "entry": _describe_sync_entry(target)}
+    except Exception as exc:
+        logger.exception("Directory creation failed")
+        return {"status": "error", "detail": str(exc), "path": payload.path}
+
+
+@app.delete("/system/files")
+async def system_files_delete(payload: FileDeleteRequest):
+    try:
+        target = _resolve_sync_path(payload.path)
+        if not target.exists():
+            return {"status": "deleted", "path": payload.path, "existed": False}
+        if target.is_dir():
+            if payload.recursive:
+                shutil.rmtree(target)
+            else:
+                target.rmdir()
+        else:
+            target.unlink()
+        return {"status": "deleted", "path": payload.path, "existed": True}
+    except Exception as exc:
+        logger.exception("Delete failed")
+        return {"status": "error", "detail": str(exc), "path": payload.path}
+
+
+if HAS_MULTIPART:
+    @app.post("/system/sync")
+    async def sync_codebase(file: UploadFile = File(...), restart: bool = False):
+        temp_zip = os.path.join(tempfile.gettempdir(), "kapo_update.zip")
+        try:
+            with open(temp_zip, "wb") as buffer:
+                shutil.copyfileobj(file.file, buffer)
+            with zipfile.ZipFile(temp_zip, "r") as zip_ref:
+                zip_ref.extractall(_sync_target_root())
+            if restart:
+                _restart_process()
+            return {"status": "synced", "target_root": _sync_target_root(), "restart_scheduled": restart}
+        except Exception as exc:
+            logger.exception("Code sync failed")
+            return {"status": "error", "detail": str(exc)}
+
+    @app.post("/system/archive/upload")
+    async def system_archive_upload(file: UploadFile = File(...), target_path: str = "", restart: bool = False):
+        temp_zip = os.path.join(tempfile.gettempdir(), "kapo_archive_upload.zip")
+        try:
+            extract_root = _resolve_sync_path(target_path)
+            extract_root.mkdir(parents=True, exist_ok=True)
+            with open(temp_zip, "wb") as buffer:
+                shutil.copyfileobj(file.file, buffer)
+            with zipfile.ZipFile(temp_zip, "r") as zip_ref:
+                zip_ref.extractall(extract_root)
+            if restart:
+                _restart_process()
+            return {
+                "status": "extracted",
+                "target_root": str(extract_root),
+                "restart_scheduled": restart,
+            }
+        except Exception as exc:
+            logger.exception("Archive upload failed")
+            return {"status": "error", "detail": str(exc)}
+else:
+    @app.post("/system/sync")
+    async def sync_codebase_unavailable():
+        return {"status": "error", "detail": "python-multipart is required for /system/sync"}
+
+    @app.post("/system/archive/upload")
+    async def system_archive_upload_unavailable():
+        return {"status": "error", "detail": "python-multipart is required for /system/archive/upload"}
+
+
+@app.post("/system/restart")
+async def system_restart(req: RestartRequest | None = None):
+    delay_sec = req.delay_sec if req else 1.0
+    if _is_hf_space_runtime():
+        return {
+            "status": "skipped",
+            "reason": "restart_disabled_on_hf_space",
+            "delay_sec": delay_sec,
+            "target_root": _sync_target_root(),
+        }
+    _restart_process(delay_sec=delay_sec)
+    return {
+        "status": "restarting",
+        "delay_sec": delay_sec,
+        "target_root": _sync_target_root(),
+    }
+
+
+def _health_payload(check_executor: bool = False, executor_url: str | None = None) -> dict[str, Any]:
+    cfg = load_config()
+    base_exec_url = (executor_url or os.getenv("EXECUTOR_URL", "")).strip().rstrip("/")
+    exec_ok = False
+    exec_checked = False
+    exec_error = None
+    health_timeout = int(cfg.get("REQUEST_TIMEOUT_SEC", 20) or 20)
+    health_retries = max(1, int(cfg.get("REQUEST_RETRIES", 2) or 2))
+
+    if base_exec_url and check_executor:
+        exec_checked = True
+        for _ in range(health_retries):
+            try:
+                response = requests.get(
+                    f"{base_exec_url}/health",
+                    headers=get_executor_headers(cfg),
+                    timeout=health_timeout,
+                )
+                exec_ok = response.status_code == 200
+                if exec_ok:
+                    exec_error = None
+                    break
+                exec_error = response.text
+            except Exception as exc:
+                exec_error = str(exc)
+
+    faiss_path = cfg.get("FAISS_INDEX_PATH")
+    return {
+        "status": "ok",
+        "model_loaded": MODEL is not None,
+        "model_error": MODEL_ERROR,
+        "embedding_loaded": EMBED_MODEL is not None,
+        "faiss_ok": bool(faiss_path and os.path.exists(faiss_path)),
+        "executor_checked": exec_checked,
+        "executor_ok": exec_ok,
+        "executor_error": exec_error,
+        "remote_brain_only": str(os.getenv("REMOTE_BRAIN_ONLY", "")).strip().lower() in {"1", "true", "yes", "on"},
+        "runtime_root": os.getenv("KAPO_RUNTIME_ROOT", ""),
+        "sync_root": _sync_target_root(),
+        "timestamp": time.time(),
+    }
+
+
+def _decode_b64_text(value: str) -> str:
+    raw = str(value or "").strip()
+    if not raw:
+        return ""
+    padding = "=" * (-len(raw) % 4)
+    try:
+        return base64.urlsafe_b64decode((raw + padding).encode("utf-8")).decode("utf-8").strip()
+    except Exception:
+        return ""
+
+
+def _runtime_modernization_snapshot() -> dict[str, Any]:
+    bootstrap = DRIVE_STATE.ensure_bootstrap_loaded(force=False) or {}
+    patch_manifest_url = str(
+        os.getenv("KAPO_PATCH_MANIFEST_URL", "")
+        or bootstrap.get("patch_manifest_url")
+        or ""
+    ).strip()
+    remote_env_url = _decode_b64_text(os.getenv("KAPO_REMOTE_ENV_URL_B64", "")) or str(os.getenv("KAPO_REMOTE_ENV_URL", "") or "").strip()
+    public_url = str(os.getenv("BRAIN_PUBLIC_URL", "") or LAST_BRAIN_URL_REPORT.get("url") or _load_saved_public_url() or "").strip()
+    applied_version = _load_applied_runtime_version()
+    control_plane_url = str(os.getenv("KAPO_CONTROL_PLANE_URL", "") or "").strip()
+    queue_name = str(os.getenv("KAPO_CLOUDFLARE_QUEUE_NAME", "") or "").strip()
+    return {
+        "shared_state_backend": _shared_state_backend(),
+        "firebase_enabled": str(os.getenv("FIREBASE_ENABLED", "0")).strip().lower() in {"1", "true", "yes", "on"},
+        "drive": {
+            "folder_id": str(os.getenv("GOOGLE_DRIVE_SHARED_STATE_FOLDER_ID", "") or os.getenv("GOOGLE_DRIVE_STORAGE_FOLDER_ID", "") or "").strip(),
+            "prefix": str(os.getenv("GOOGLE_DRIVE_SHARED_STATE_PREFIX", "") or os.getenv("GOOGLE_DRIVE_STORAGE_PREFIX", "") or "").strip(),
+            "bootstrap_loaded": bool(bootstrap),
+        },
+        "bootstrap": {
+            "configured": bool(str(os.getenv("KAPO_BOOTSTRAP_URL", "") or os.getenv("GOOGLE_DRIVE_BOOTSTRAP_URL", "") or "").strip()),
+            "url": str(os.getenv("KAPO_BOOTSTRAP_URL", "") or os.getenv("GOOGLE_DRIVE_BOOTSTRAP_URL", "") or "").strip(),
+            "loaded": bool(bootstrap),
+            "version": str(bootstrap.get("version") or "").strip(),
+            "updated_at": bootstrap.get("updated_at"),
+        },
+        "patch": {
+            "configured": bool(patch_manifest_url),
+            "manifest_url": patch_manifest_url,
+            "startup_self_update_enabled": _startup_self_update_enabled(),
+            "applied_version": applied_version,
+        },
+        "remote_env": {
+            "configured": bool(remote_env_url),
+            "loaded": str(os.getenv("KAPO_REMOTE_ENV_LOADED", "0")).strip().lower() in {"1", "true", "yes", "on"},
+            "url": remote_env_url,
+        },
+        "control_plane": {
+            "configured": bool(control_plane_url),
+            "url": control_plane_url,
+            "queue_name": queue_name,
+            "queue_configured": bool(queue_name),
+        },
+        "transport": {
+            "provider": str(os.getenv("BRAIN_TUNNEL_PROVIDER", "ngrok") or "ngrok").strip().lower(),
+            "auto_ngrok": _ngrok_bootstrap_enabled(),
+            "reuse_public_url_on_restart": _reuse_public_url_on_restart(),
+            "public_url": public_url,
+            "executor_url": str(os.getenv("EXECUTOR_URL", "") or "").strip(),
+        },
+        "runtime": {
+            "root": str(_sync_target_root()),
+            "model_profile_id": str(os.getenv("MODEL_PROFILE_ID", "") or "").strip(),
+            "model_loaded": MODEL is not None,
+            "embed_loaded": EMBED_MODEL is not None,
+        },
+    }
+
+
+def _persist_runtime_state_snapshot(reason: str = "periodic") -> dict[str, Any]:
+    payload = _health_payload(check_executor=False)
+    public_url = os.getenv("BRAIN_PUBLIC_URL") or _load_saved_public_url() or ""
+    state_id = _brain_state_id()
+    FIREBASE.set_document(
+        "brains",
+        public_url or state_id,
+        {
+            "url": public_url,
+            "health": payload,
+            "status": "healthy" if payload["model_loaded"] else "degraded",
+            "model_repo": os.getenv("MODEL_REPO", DEFAULT_MODEL_REPO),
+            "model_file": os.getenv("MODEL_FILE", DEFAULT_MODEL_FILE),
+            "model_profile_id": os.getenv("MODEL_PROFILE_ID", DEFAULT_MODEL_PROFILE_ID),
+            "roles": os.getenv("BRAIN_ROLES", "supervisor,chat,coding,planner,arabic,fallback"),
+            "languages": os.getenv("BRAIN_LANGUAGES", "ar,en"),
+            "updated_at": time.time(),
+            "source": reason,
+        },
+        min_interval_sec=5.0,
+    )
+    FIREBASE.set_document(
+        "brain_runtime",
+        state_id,
+        {
+            "brain_url": public_url,
+            "reason": reason,
+            "health": payload,
+            "recent_logs": list(RUNTIME_LOG_BUFFER)[-25:],
+            "updated_at": time.time(),
+        },
+        min_interval_sec=5.0,
+    )
+    return payload
+
+
+def _runtime_state_pulse() -> None:
+    interval = max(20.0, float(os.getenv("BRAIN_STATE_SYNC_INTERVAL_SEC", "60") or 60))
+    while True:
+        try:
+            _persist_runtime_state_snapshot(reason="background_pulse")
+        except Exception:
+            logger.warning("Background runtime state sync failed", exc_info=True)
+        time.sleep(interval)
+
+
+@app.get("/health")
+async def health(executor_url: str | None = None, check_executor: bool = False):
+    payload = _health_payload(check_executor=check_executor, executor_url=executor_url)
+    _persist_runtime_state_snapshot(reason="health_endpoint")
+    return payload
+
+
+# KAPO HF SPACE TRANSFORMERS PATCH
+def _kapo_hf_transformers_enabled() -> bool:
+    return str(os.getenv('KAPO_HF_TRANSFORMERS_RUNTIME', '0')).strip().lower() in {'1', 'true', 'yes', 'on'}
+
+def ensure_model_loaded(repo_id: str, filename: str, hf_token: str | None = None) -> None:
+    global MODEL, MODEL_ERROR, MODEL_META
+    repo_id = (repo_id or '').strip()
+    filename = (filename or '').strip()
+    if not repo_id:
+        MODEL = None
+        MODEL_ERROR = 'model repo missing'
+        return
+    if _kapo_hf_transformers_enabled():
+        try:
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+            tokenizer = AutoTokenizer.from_pretrained(repo_id, token=hf_token, trust_remote_code=True)
+            model = AutoModelForCausalLM.from_pretrained(repo_id, token=hf_token, trust_remote_code=True, device_map='cpu')
+            if hasattr(model, 'eval'):
+                model.eval()
+            MODEL = {'kind': 'transformers', 'model': model, 'tokenizer': tokenizer}
+            MODEL_ERROR = None
+            MODEL_META = {'repo_id': repo_id, 'filename': filename, 'path': None}
+            logger.info('Loaded transformers model %s', repo_id)
+            return
+        except Exception as exc:
+            MODEL = None
+            MODEL_ERROR = f'transformers model load failed: {exc}'
+            logger.exception('Transformers model load failed')
+            return
+    if not filename:
+        MODEL = None
+        MODEL_ERROR = 'model file missing'
+        return
+    try:
+        model_path = _download_model(repo_id, filename, hf_token=hf_token)
+    except Exception as exc:
+        MODEL = None
+        MODEL_ERROR = f'model download failed: {exc}'
+        logger.exception('Model download failed')
+        return
+    try:
+        from llama_cpp import Llama
+        MODEL = Llama(model_path=model_path, n_ctx=4096)
+        MODEL_ERROR = None
+        MODEL_META = {'repo_id': repo_id, 'filename': filename, 'path': model_path}
+        logger.info('Loaded model %s/%s', repo_id, filename)
+    except Exception as exc:
+        MODEL = None
+        MODEL_ERROR = f'model load failed: {exc}'
+        logger.exception('Model load failed')
+
+def _generate_response(user_input: str, history: list[dict[str, str]], context_block: str) -> str:
+    language = _detect_language(user_input)
+    exact_reply = _extract_exact_reply_instruction_safe(user_input)
+    if exact_reply:
+        return exact_reply
+    fast_reply = _project_specific_fast_reply(user_input)
+    if fast_reply:
+        return fast_reply
+    if MODEL is None:
+        try:
+            _load_default_model()
+        except Exception:
+            logger.exception('Lazy model load failed')
+        if MODEL is None:
+            if language == 'ar':
+                return 'الخدمة تعمل لكن توليد الرد الحر غير متاح الآن لأن النموذج غير محمل.'
+            return 'The Brain is online, but natural chat generation is unavailable because the model is not loaded.'
+    prompt = _build_chat_prompt(user_input, history, context_block)
+    try:
+        max_tokens = 80 if language == 'ar' else 96
+        if isinstance(MODEL, dict) and MODEL.get('kind') == 'transformers':
+            tokenizer = MODEL['tokenizer']
+            model = MODEL['model']
+            inputs = tokenizer(prompt, return_tensors='pt', truncation=True, max_length=2048)
+            if hasattr(model, 'device'):
+                inputs = {k: v.to(model.device) if hasattr(v, 'to') else v for k, v in inputs.items()}
+            output_ids = model.generate(**inputs, max_new_tokens=max_tokens, do_sample=False, pad_token_id=tokenizer.eos_token_id)
+            generated = output_ids[0][inputs['input_ids'].shape[1]:]
+            text = tokenizer.decode(generated, skip_special_tokens=True).strip()
+        else:
+            output = MODEL(prompt, max_tokens=max_tokens, temperature=0.1, top_p=0.85, stop=['\nUser:', '\nUSER:', '\n###', '<|EOT|>'])
+            text = output['choices'][0]['text'].strip()
+        if _response_looks_bad(text, language):
+            return _fallback_response(user_input)
+        return text or ('تم استلام رسالتك.' if language == 'ar' else 'I received your message.')
+    except Exception:
+        logger.exception('Model generation failed')
+        if language == 'ar':
+            return 'فهمت طلبك، لكن حدث خطأ أثناء توليد الرد النصي.'
+        return 'I understood your request, but text generation failed.'

brain_server/api/routes_analyze.py

@@ -0,0 +1,48 @@
+"""Routes for analyze/store."""
+import time
+import logging
+import os
+from typing import Dict, Any
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from api.deps import get_logger
+import requests
+from memory.episodic_db import EpisodicDB
+from api.deps import is_remote_brain_only, load_config
+
+router = APIRouter()
+logger = get_logger("kapo.brain.analyze")
+
+
+class AnalyzeRequest(BaseModel):
+    request_id: str
+    payload: Dict[str, Any]
+    auth_token: str | None = None
+    timestamp: float | None = None
+
+
+@router.post("/analyze")
+async def analyze(req: AnalyzeRequest):
+    """????? ??????? ?? ??????? ??????? (Episodic)."""
+    try:
+        if not is_remote_brain_only():
+            db = EpisodicDB()
+            db.insert_experience(
+                task=req.payload.get("task", "unknown"),
+                plan=req.payload.get("plan", {}),
+                tools_used=req.payload.get("tools_used", {}),
+                result=req.payload.get("result", {}),
+                success=1 if req.payload.get("success") else 0,
+            )
+        else:
+            try:
+                hub = load_config().get("LOCAL_HUB_URL") or os.getenv("LOCAL_HUB_URL")
+                if hub:
+                    requests.post(f"{hub}/memory/store", json={"request_id": req.request_id, "payload": req.payload}, timeout=10)
+            except Exception:
+                logger.warning("Local hub store failed")
+        return {"status": "stored", "timestamp": time.time()}
+    except Exception as exc:
+        logger.exception("Analyze failed")
+        raise HTTPException(status_code=500, detail=str(exc))

brain_server/api/routes_execute.py

@@ -0,0 +1,120 @@
+"""Routes for remote execution via the local executive agent."""
+import time
+from typing import Any
+
+import requests
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from agents.auto_heal_agent import AutoHealAgent
+from agents.memory_agent import MemoryAgent
+from agents.supervisor_agent import SupervisorAgent
+from agents.tool_selector_agent import ToolSelectorAgent
+from api.deps import get_executor_headers, get_executor_url, get_logger, is_remote_brain_only, load_config
+
+router = APIRouter()
+logger = get_logger("kapo.brain.execute")
+
+
+class ExecuteRequest(BaseModel):
+    request_id: str
+    plan: dict[str, Any] | list[dict[str, Any]]
+    auth_token: str | None = None
+    timestamp: float | None = None
+    executor_url: str | None = None
+
+
+def _normalize_executor_url(url: str | None) -> str:
+    if not url:
+        return ""
+    value = url.strip()
+    if not value:
+        return ""
+    if "://" not in value:
+        value = f"http://{value}"
+    return value.rstrip("/")
+
+
+def _extract_steps(plan: dict[str, Any] | list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if isinstance(plan, list):
+        return [_normalize_step(step, index) for index, step in enumerate(plan, start=1)]
+    if isinstance(plan, dict):
+        steps = plan.get("steps")
+        if isinstance(steps, list):
+            return [_normalize_step(step, index) for index, step in enumerate(steps, start=1)]
+    return []
+
+
+def _normalize_step(step: dict[str, Any], index: int) -> dict[str, Any]:
+    if not isinstance(step, dict):
+        return {"id": f"step-{index}", "action": "execute", "input": str(step), "tool_hint": "python"}
+    normalized = dict(step)
+    if not str(normalized.get("id", "")).strip():
+        normalized["id"] = f"step-{index}"
+    if not str(normalized.get("input", "")).strip():
+        for key in ("description", "title", "summary", "task", "prompt"):
+            value = str(normalized.get(key, "")).strip()
+            if value:
+                normalized["input"] = value
+                break
+    if not str(normalized.get("action", "")).strip():
+        normalized["action"] = "execute"
+    if not str(normalized.get("tool_hint", "")).strip():
+        normalized["tool_hint"] = "python"
+    return normalized
+
+
+@router.post("/execute")
+async def execute(req: ExecuteRequest):
+    cfg = load_config()
+    tool_selector = ToolSelectorAgent()
+    supervisor = SupervisorAgent()
+    auto_heal = AutoHealAgent()
+    memory = MemoryAgent()
+
+    base_exec_url = _normalize_executor_url(req.executor_url) or get_executor_url(cfg)
+    exec_url = f"{base_exec_url}/execute"
+    exec_headers = get_executor_headers(cfg)
+    timeout = int(cfg.get("REQUEST_TIMEOUT_SEC", 20) or 20)
+    retries = int(cfg.get("REQUEST_RETRIES", 2) or 2)
+
+    try:
+        results: list[dict[str, Any]] = []
+        for step in _extract_steps(req.plan):
+            tool = tool_selector.select_tool(step)
+            payload = {
+                "request_id": req.request_id,
+                "step_id": step.get("id"),
+                "command": tool.get("command"),
+                "files": tool.get("files", {}),
+                "env": tool.get("env", {}),
+                "timestamp": time.time(),
+            }
+            attempt = 0
+            last_err = None
+            while attempt <= retries:
+                try:
+                    response = requests.post(exec_url, json=payload, headers=exec_headers, timeout=timeout)
+                    if response.status_code == 200:
+                        item = response.json()
+                        item["selected_tool"] = tool.get("tool")
+                        results.append(item)
+                        last_err = None
+                        break
+                    last_err = response.text
+                except Exception as exc:
+                    last_err = str(exc)
+                attempt += 1
+
+            if last_err:
+                results.append({"error": last_err, "step": step, "auto_heal": auto_heal.suggest(last_err, step)})
+
+        report = supervisor.review(results)
+        snapshot = {"execution": results, "report": report}
+        if not is_remote_brain_only():
+            memory.write_short_term(req.request_id, snapshot)
+
+        return {"status": "ok", "results": results, "report": report, "timestamp": time.time()}
+    except Exception as exc:
+        logger.exception("Execution failed")
+        raise HTTPException(status_code=500, detail=str(exc))

brain_server/api/routes_plan.py

@@ -0,0 +1,67 @@
+"""Routes for planning."""
+import time
+import uuid
+import logging
+from typing import Dict, Any, List
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from api.deps import get_executor_headers, get_executor_url, get_logger, load_config
+from agents.planner_agent import PlannerAgent
+from agents.reasoning_agent import ReasoningAgent
+from agents.memory_agent import MemoryAgent
+from api.deps import is_remote_brain_only
+import requests
+
+router = APIRouter()
+logger = get_logger("kapo.brain.plan")
+
+
+class PlanRequest(BaseModel):
+    request_id: str
+    user_input: str
+    context: Dict[str, Any] = {}
+    auth_token: str | None = None
+    timestamp: float | None = None
+
+
+class PlanResponse(BaseModel):
+    plan_id: str
+    plan: List[Dict[str, Any]]
+    metadata: Dict[str, Any]
+
+
+@router.post("/plan", response_model=PlanResponse)
+async def plan(req: PlanRequest):
+    """????? ??? ????? ???????."""
+    try:
+        logger.info("Plan requested", extra={"request_id": req.request_id, "component": "plan"})
+        planner = PlannerAgent()
+        reasoning = ReasoningAgent()
+        memory = MemoryAgent()
+        plan_steps = planner.run(req.user_input, req.context)
+        rationale = reasoning.run(req.user_input, plan_steps)
+        plan_id = str(uuid.uuid4())
+        if not is_remote_brain_only():
+            memory.write_short_term(req.request_id, {"plan": plan_steps, "rationale": rationale})
+        else:
+            try:
+                cfg = load_config()
+                hub = get_executor_url(cfg)
+                if hub:
+                    requests.post(
+                        f"{hub}/memory/store",
+                        json={"request_id": req.request_id, "payload": {"plan": plan_steps, "rationale": rationale}},
+                        headers=get_executor_headers(cfg),
+                        timeout=(3, 4),
+                    )
+            except Exception:
+                logger.warning("Local hub store failed")
+        return PlanResponse(
+            plan_id=plan_id,
+            plan=plan_steps,
+            metadata={"rationale": rationale, "timestamp": time.time()},
+        )
+    except Exception as exc:
+        logger.exception("Plan failed")
+        raise HTTPException(status_code=500, detail=str(exc))

brain_server/config/config.yaml

@@ -0,0 +1,26 @@
+# ??????? Brain Server
+MODEL_PATH: "${MODEL_PATH}"
+BRAIN_HOST: "${BRAIN_HOST}"
+BRAIN_PORT: "${BRAIN_PORT}"
+EXECUTOR_HOST: "${EXECUTOR_HOST}"
+EXECUTOR_PORT: "${EXECUTOR_PORT}"
+DB_PATH: "${DB_PATH}"
+TOOLS_DB_PATH: "${TOOLS_DB_PATH}"
+FAISS_INDEX_PATH: "${FAISS_INDEX_PATH}"
+EMBED_MODEL: "${EMBED_MODEL}"
+LOG_LEVEL: "${LOG_LEVEL}"
+WHITELIST_COMMANDS: "${WHITELIST_COMMANDS}"
+BLACKLIST_COMMANDS: "${BLACKLIST_COMMANDS}"
+REQUEST_TIMEOUT_SEC: 20
+REQUEST_RETRIES: 2
+REMOTE_BRAIN_ONLY: "${REMOTE_BRAIN_ONLY}"
+BRAIN_REMOTE_KNOWLEDGE_ENABLED: "${BRAIN_REMOTE_KNOWLEDGE_ENABLED}"
+BRAIN_REMOTE_WEB_SEARCH_ENABLED: "${BRAIN_REMOTE_WEB_SEARCH_ENABLED}"
+BRAIN_REMOTE_TRACE_STORE_ENABLED: "${BRAIN_REMOTE_TRACE_STORE_ENABLED}"
+BRAIN_REMOTE_AUTO_INGEST_ENABLED: "${BRAIN_REMOTE_AUTO_INGEST_ENABLED}"
+BRAIN_LOCAL_RAG_FALLBACK_ENABLED: "${BRAIN_LOCAL_RAG_FALLBACK_ENABLED}"
+EXECUTOR_CONNECT_TIMEOUT_SEC: "${EXECUTOR_CONNECT_TIMEOUT_SEC}"
+BRAIN_REMOTE_KNOWLEDGE_TIMEOUT_SEC: "${BRAIN_REMOTE_KNOWLEDGE_TIMEOUT_SEC}"
+BRAIN_REMOTE_WEB_SEARCH_TIMEOUT_SEC: "${BRAIN_REMOTE_WEB_SEARCH_TIMEOUT_SEC}"
+BRAIN_REMOTE_TRACE_STORE_TIMEOUT_SEC: "${BRAIN_REMOTE_TRACE_STORE_TIMEOUT_SEC}"
+BRAIN_REMOTE_AUTO_INGEST_TIMEOUT_SEC: "${BRAIN_REMOTE_AUTO_INGEST_TIMEOUT_SEC}"

brain_server/config/logging.yaml

@@ -0,0 +1,22 @@
+version: 1
+formatters:
+  json:
+    class: pythonjsonlogger.jsonlogger.JsonFormatter
+    format: "%(asctime)s %(levelname)s %(name)s %(message)s %(request_id)s %(component)s"
+  console:
+    format: "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+handlers:
+  console:
+    class: logging.StreamHandler
+    formatter: console
+  json:
+    class: logging.StreamHandler
+    formatter: json
+root:
+  level: INFO
+  handlers: [console]
+loggers:
+  kapo:
+    level: INFO
+    handlers: [json]
+    propagate: false

brain_server/kaggle_bootstrap.py

@@ -0,0 +1,26 @@
+"""Bootstrap a Kaggle dataset copy of brain_server into /kaggle/working and print run guidance."""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def main() -> None:
+    source_root = Path(__file__).resolve().parent
+    runtime_root = Path(os.getenv("KAPO_RUNTIME_ROOT") or "/kaggle/working/brain_server").resolve()
+
+    if source_root != runtime_root:
+        if runtime_root.exists():
+            shutil.rmtree(runtime_root, ignore_errors=True)
+        shutil.copytree(source_root, runtime_root)
+
+    print(f"Bootstrapped brain_server to: {runtime_root}")
+    print("Next steps:")
+    print(f"  %cd {runtime_root}")
+    print("  !pip install --default-timeout=1000 --no-cache-dir -r requirements.txt")
+    print("  !python -m uvicorn api.main:app --host 0.0.0.0 --port 7860")
+
+
+if __name__ == "__main__":
+    main()

brain_server/langgraph/__init__.py

@@ -0,0 +1 @@
+"""LangGraph wrapper package."""

brain_server/langgraph/agent_prompts.py

@@ -0,0 +1,87 @@
+"""Prompts ??? ???? (Arabic + short English example)."""
+import logging
+
+logger = logging.getLogger("kapo.prompts")
+
+PLANNER_PROMPT = """
+[Planner Agent]
+??? ????? ?? ????? ???? ???????? ??? ??? ??????? JSON.
+
+??????? (JSON Schema):
+{
+  "request_id": "str",
+  "user_input": "str",
+  "context": {"...": "..."}
+}
+
+??????? ??????? (JSON Schema):
+{
+  "steps": [
+    {"id": "str", "action": "str", "tool_hint": "str", "files": {}, "env": {}}
+  ],
+  "assumptions": ["..."]
+}
+
+???? ????:
+Input: {"request_id":"r1","user_input":"??? ????","context":{}}
+Output: {"steps":[{"id":"s1","action":"analyze","tool_hint":"python"}],"assumptions":[]}
+
+English short example:
+Input: {"request_id":"r1","user_input":"Summarize logs"}
+Output: {"steps":[{"id":"s1","action":"summarize","tool_hint":"python"}]}
+"""
+
+REASONING_PROMPT = """
+[Reasoning Agent]
+??? ????? ???? ??????? ???????.
+
+Input Schema:
+{"user_input":"str","plan":{"steps":[...]}}
+
+Output Schema:
+{"rationale":"str","risks":["..."],"notes":"str"}
+"""
+
+TOOL_SELECTOR_PROMPT = """
+[Tool Selector Agent]
+???? ?????? ?????? ??? ????.
+
+Input Schema:
+{"step":{"id":"str","action":"str"},"tools":[{"tool_name":"str"}]}
+
+Output Schema:
+{"tool_name":"str","command":"str","reason":"str"}
+"""
+
+SUPERVISOR_PROMPT = """
+[Supervisor Agent]
+??? ????? ??????? ???? ?????? ?? ????? ?? ??????.
+
+Input Schema:
+{"results":[{"exit_code":0,"stdout":""}]}
+
+Output Schema:
+{"success":true,"report":"str","next_actions":["..."]}
+"""
+
+AUTO_HEAL_PROMPT = """
+[Auto-Heal Agent]
+??? ??????? ?????? ??????? ????? ???????.
+
+Input Schema:
+{"error_text":"str","context":{"step":{}}}
+
+Output Schema:
+{"suggested_fix":"str","reexecute":true}
+"""
+
+MEMORY_PROMPT = """
+[Memory Agent]
+??? ?? ??? ?????? ?? ??????? ?????? ????????.
+
+Input Schema:
+{"event":{...},"policy":"str"}
+
+Output Schema:
+{"store_short_term":true,"store_episodic":true,"keys":["..."]}
+"""

brain_server/langgraph/graph_definition.py

@@ -0,0 +1,46 @@
+"""????? ???? LangGraph ?? ???? ????."""
+import logging
+from typing import Dict, Any
+from agents.planner_agent import PlannerAgent
+from agents.reasoning_agent import ReasoningAgent
+from agents.tool_selector_agent import ToolSelectorAgent
+from agents.supervisor_agent import SupervisorAgent
+from agents.auto_heal_agent import AutoHealAgent
+from agents.memory_agent import MemoryAgent
+from api.deps import get_logger
+
+logger = get_logger("kapo.langgraph")
+
+
+class SimpleGraph:
+    """???? ???? ?? LangGraph ??? ???? ???????."""
+
+    def run(self, user_input: str, context: Dict[str, Any]):
+        planner = PlannerAgent()
+        reasoning = ReasoningAgent()
+        tool_selector = ToolSelectorAgent()
+        supervisor = SupervisorAgent()
+        auto_heal = AutoHealAgent()
+        memory = MemoryAgent()
+
+        plan = planner.run(user_input, context)
+        rationale = reasoning.run(user_input, plan)
+        memory.write_short_term("last_plan", {"plan": plan, "rationale": rationale})
+        return {
+            "plan": plan,
+            "rationale": rationale,
+            "tool_selector": tool_selector,
+            "supervisor": supervisor,
+            "auto_heal": auto_heal,
+        }
+
+
+def get_graph():
+    """????? ??????? LangGraph ?? ????? ???? ?????? SimpleGraph."""
+    try:
+        import langgraph  # noqa: F401
+        logger.info("Using langgraph")
+        return SimpleGraph()
+    except Exception:
+        logger.warning("LangGraph not available; using SimpleGraph")
+        return SimpleGraph()

brain_server/memory/__init__.py

@@ -0,0 +1 @@
+"""Memory package."""

brain_server/memory/episodic_db.py

@@ -0,0 +1,91 @@
+"""Episodic SQLite storage."""
+import json
+import sqlite3
+import time
+import logging
+from typing import Dict, Any, List
+from api.deps import load_config, get_logger
+
+logger = get_logger("kapo.memory.episodic")
+
+
+class EpisodicDB:
+    def __init__(self):
+        cfg = load_config()
+        self.db_path = cfg.get("DB_PATH") or "./episodic.db"
+        self._init_db()
+
+    def _init_db(self):
+        conn = sqlite3.connect(self.db_path)
+        cur = conn.cursor()
+        cur.execute(
+            """
+            CREATE TABLE IF NOT EXISTS experiences (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                task TEXT,
+                plan TEXT,
+                tools_used TEXT,
+                result TEXT,
+                success INTEGER,
+                timestamp TEXT
+            )
+            """
+        )
+        conn.commit()
+        conn.close()
+
+    def insert_experience(self, task: str, plan: Dict[str, Any], tools_used: Dict[str, Any], result: Dict[str, Any], success: int):
+        conn = sqlite3.connect(self.db_path)
+        cur = conn.cursor()
+        cur.execute(
+            """INSERT INTO experiences(task, plan, tools_used, result, success, timestamp)
+               VALUES(?,?,?,?,?,?)""",
+            (task, json.dumps(plan), json.dumps(tools_used), json.dumps(result), success, time.strftime("%Y-%m-%dT%H:%M:%S")),
+        )
+        conn.commit()
+        conn.close()
+
+    def list_recent(self, limit: int = 20) -> List[Dict[str, Any]]:
+        conn = sqlite3.connect(self.db_path)
+        cur = conn.cursor()
+        cur.execute("SELECT task, plan, tools_used, result, success, timestamp FROM experiences ORDER BY id DESC LIMIT ?", (limit,))
+        rows = cur.fetchall()
+        conn.close()
+        out = []
+        for r in rows:
+            out.append({
+                "task": r[0],
+                "plan": json.loads(r[1]),
+                "tools_used": json.loads(r[2]),
+                "result": json.loads(r[3]),
+                "success": r[4],
+                "timestamp": r[5],
+            })
+        return out
+
+    def search_similar(self, text: str, top_k: int = 3):
+        """??? ?????? ??? embeddings ?????? (?????? ?????)."""
+        try:
+            from sentence_transformers import SentenceTransformer
+            cfg = load_config()
+            model = cfg.get("EMBED_MODEL") or "sentence-transformers/all-MiniLM-L6-v2"
+            embedder = SentenceTransformer(model)
+            records = self.list_recent(limit=200)
+            if not records:
+                return []
+            texts = [r.get("task", "") for r in records]
+            vectors = embedder.encode(texts, show_progress_bar=False)
+            qv = embedder.encode([text])[0]
+            # cosine similarity
+            def cos(a, b):
+                import math
+                dot = sum(x*y for x, y in zip(a, b))
+                na = math.sqrt(sum(x*x for x in a))
+                nb = math.sqrt(sum(x*x for x in b))
+                return dot / (na*nb + 1e-9)
+            scored = [(cos(qv, v), r) for v, r in zip(vectors, records)]
+            scored.sort(key=lambda x: x[0], reverse=True)
+            return [r for _, r in scored[:top_k]]
+        except Exception:
+            logger.exception("Similarity search failed")
+            return []

brain_server/memory/knowledge_vector.py

@@ -0,0 +1,84 @@
+"""Knowledge vector store using sentence-transformers + FAISS."""
+import os
+import sqlite3
+import logging
+from typing import List
+from api.deps import load_config, get_logger
+
+logger = get_logger("kapo.memory.knowledge")
+
+
+class KnowledgeVectorStore:
+    def __init__(self):
+        cfg = load_config()
+        self.index_path = cfg.get("FAISS_INDEX_PATH") or "./faiss.index"
+        self.meta_db = self.index_path + ".meta.db"
+        self.embed_model = cfg.get("EMBED_MODEL") or "sentence-transformers/all-MiniLM-L6-v2"
+        self._init_meta()
+
+    def _init_meta(self):
+        conn = sqlite3.connect(self.meta_db)
+        cur = conn.cursor()
+        cur.execute(
+            """
+            CREATE TABLE IF NOT EXISTS vectors (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                source TEXT,
+                content TEXT
+            )
+            """
+        )
+        conn.commit()
+        conn.close()
+
+    def _load_embedder(self):
+        from sentence_transformers import SentenceTransformer
+        return SentenceTransformer(self.embed_model)
+
+    def _load_index(self, dim: int):
+        import faiss
+        if os.path.exists(self.index_path):
+            return faiss.read_index(self.index_path)
+        return faiss.IndexFlatL2(dim)
+
+    def add_texts(self, texts: List[str], source: str = "unknown"):
+        try:
+            embedder = self._load_embedder()
+            embeddings = embedder.encode(texts, show_progress_bar=False)
+            dim = len(embeddings[0])
+            index = self._load_index(dim)
+            index.add(embeddings)
+            import faiss
+            faiss.write_index(index, self.index_path)
+
+            conn = sqlite3.connect(self.meta_db)
+            cur = conn.cursor()
+            for t in texts:
+                cur.execute("INSERT INTO vectors(source, content) VALUES(?,?)", (source, t))
+            conn.commit()
+            conn.close()
+        except Exception:
+            logger.exception("Failed to add texts")
+
+    def query(self, q: str, top_k: int = 3):
+        try:
+            embedder = self._load_embedder()
+            qv = embedder.encode([q])
+            import faiss
+            if not os.path.exists(self.index_path):
+                return []
+            index = faiss.read_index(self.index_path)
+            scores, ids = index.search(qv, top_k)
+            conn = sqlite3.connect(self.meta_db)
+            cur = conn.cursor()
+            results = []
+            for idx in ids[0]:
+                cur.execute("SELECT source, content FROM vectors WHERE id=?", (int(idx) + 1,))
+                row = cur.fetchone()
+                if row:
+                    results.append({"source": row[0], "content": row[1]})
+            conn.close()
+            return results
+        except Exception:
+            logger.exception("Query failed")
+            return []

brain_server/memory/short_term.py

@@ -0,0 +1,37 @@
+"""Short-term in-memory store with TTL."""
+import time
+import logging
+from typing import Any, Dict
+
+logger = logging.getLogger("kapo.memory.short_term")
+
+
+class ShortTermMemory:
+    def __init__(self, ttl_sec: int = 1800, max_items: int = 500):
+        self.ttl_sec = ttl_sec
+        self.max_items = max_items
+        self._store: Dict[str, Any] = {}
+        self._ts: Dict[str, float] = {}
+
+    def _cleanup(self):
+        try:
+            now = time.time()
+            expired = [k for k, t in self._ts.items() if now - t > self.ttl_sec]
+            for k in expired:
+                self._store.pop(k, None)
+                self._ts.pop(k, None)
+            if len(self._store) > self.max_items:
+                for k in list(self._store.keys())[: len(self._store) - self.max_items]:
+                    self._store.pop(k, None)
+                    self._ts.pop(k, None)
+        except Exception:
+            logger.exception("Cleanup failed")
+
+    def set(self, key: str, value: Any):
+        self._store[key] = value
+        self._ts[key] = time.time()
+        self._cleanup()
+
+    def get(self, key: str):
+        self._cleanup()
+        return self._store.get(key)

brain_server/rag/__init__.py

@@ -0,0 +1 @@
+"""RAG package."""

brain_server/rag/loader.py

@@ -0,0 +1,19 @@
+"""RAG Loader: ????? ????? ?? ???????."""
+import os
+import logging
+from typing import List
+from api.deps import get_logger
+
+logger = get_logger("kapo.rag.loader")
+
+
+def load_texts(paths: List[str]) -> List[str]:
+    texts = []
+    for p in paths:
+        try:
+            if os.path.exists(p):
+                with open(p, "r", encoding="utf-8") as f:
+                    texts.append(f.read())
+        except Exception:
+            logger.exception("Failed to load %s", p)
+    return texts

brain_server/rag/retriever.py

@@ -0,0 +1,14 @@
+"""RAG Retriever: ??????? FAISS."""
+import logging
+from memory.knowledge_vector import KnowledgeVectorStore
+
+logger = logging.getLogger("kapo.rag.retriever")
+
+
+def retrieve(query: str, top_k: int = 3):
+    try:
+        store = KnowledgeVectorStore()
+        return store.query(query, top_k=top_k)
+    except Exception:
+        logger.exception("Retrieve failed")
+        return []

brain_server/requirements.txt

@@ -0,0 +1,27 @@
+numpy<2.0.0
+fastapi>=0.115.2,<1.0
+uvicorn==0.30.1
+pydantic==2.7.3
+python-dotenv==1.0.1
+requests==2.32.3
+python-multipart>=0.0.18
+sqlalchemy==2.0.30
+sentence-transformers==3.0.1
+faiss-cpu==1.8.0
+llama-cpp-python==0.2.79
+python-json-logger==2.0.7
+langgraph==0.0.50
+huggingface_hub>=0.33.5,<2.0
+pyngrok==7.1.6
+firebase-admin==6.5.0
+starlette>=0.40.0,<1.0
+websockets==12.0
+
+sentence-transformers
+transformers
+
+peft
+bitsandbytes
+trl
+accelerate
+datasets

kapo.env

@@ -0,0 +1,31 @@
+BRAIN_AUTO_NGROK=0
+BRAIN_AUTO_PUBLISH_URL_ON_STARTUP=0
+BRAIN_LANGUAGES=ar,en
+BRAIN_PLATFORM_NAME=ai_coder_main
+BRAIN_PROVIDER=huggingface
+BRAIN_REUSE_PUBLIC_URL_ON_RESTART=0
+BRAIN_ROLES=coding,planner,fallback
+BRAIN_TEMPLATE=hf-space-cpu
+BRAIN_TUNNEL_PROVIDER=none
+FIREBASE_ENABLED=0
+FIREBASE_NAMESPACE=kapo
+FIREBASE_PROJECT_ID=citadel4travels
+GOOGLE_DRIVE_BOOTSTRAP_URL=https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG
+HF_ACCELERATOR=cpu
+HF_SPACE_DOCKER=1
+KAGGLE_AUTO_BOOTSTRAP=0
+KAPO_BOOTSTRAP_URL=https://drive.google.com/uc?export=download&id=19jyBWsQ9ciJVPi2PUigu5ti3gJ24A6TG
+KAPO_COMPUTE_PROFILE=cpu
+KAPO_HF_INFERENCE_API=1
+KAPO_HF_TRANSFORMERS_RUNTIME=0
+KAPO_LAZY_EMBED_STARTUP=1
+KAPO_LAZY_MODEL_STARTUP=1
+KAPO_PATCH_BUNDLE_URL=https://drive.google.com/uc?export=download&id=16rIe05GZihhAz7ba8E-WibKaJKbh9eu1
+KAPO_PATCH_MANIFEST_URL=https://drive.google.com/uc?export=download&id=1jLuPMCA3hp9qstZZtpBNzTK0XOmLrV8b
+KAPO_REMOTE_ENV_PASSWORD_B64=cENvSnljQ0Z6RUN2azRpcUFLVUdQLW9BbVBoTEtNOFE
+KAPO_REMOTE_ENV_URL_B64=aHR0cHM6Ly9kcml2ZS5nb29nbGUuY29tL3VjP2V4cG9ydD1kb3dubG9hZCZpZD0xdjlZRDlNYlBKNUdYNk9WanVHM3hOR05xLWJfQlJfTGY
+KAPO_SHARED_STATE_BACKEND=google_drive
+MODEL_PROFILE_ID=hf-coder-qwen25-coder-7b-instruct
+MODEL_REPO=Qwen/Qwen2.5-Coder-1.5B-Instruct
+REMOTE_BRAIN_ONLY=1
+SPACE_PUBLIC_URL=https://MrA7A1-AiCoder.hf.space

requirements.txt

@@ -0,0 +1,9 @@
+fastapi>=0.115.2,<1.0
+uvicorn==0.30.1
+pydantic==2.7.3
+python-dotenv==1.0.1
+PyYAML>=6.0,<7.0
+requests==2.32.3
+python-json-logger==2.0.7
+huggingface_hub>=0.33.5,<2.0
+starlette>=0.40.0,<1.0

shared/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities for KAPO runtimes."""

shared/google_drive_state.py

@@ -0,0 +1,409 @@
+"""Google Drive backed shared-state utilities."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+import requests
+
+
+def _safe_name(value: str, default: str = "item") -> str:
+    text = str(value or "").strip() or default
+    return "".join(ch if ch.isalnum() or ch in {"-", "_", "."} else "_" for ch in text)[:180]
+
+
+class GoogleDriveStateClient:
+    def __init__(self, logger: logging.Logger) -> None:
+        self.logger = logger
+        self._folder_cache: dict[str, str] = {}
+        self._file_cache: dict[str, str] = {}
+        self._bootstrap_lock = threading.Lock()
+        self._bootstrap_loaded_at = 0.0
+        self._bootstrap_payload: dict[str, Any] = {}
+
+    def _bootstrap_url(self) -> str:
+        return str(os.getenv("GOOGLE_DRIVE_BOOTSTRAP_URL", "") or os.getenv("KAPO_BOOTSTRAP_URL", "") or "").strip()
+
+    def _bootstrap_ttl(self) -> float:
+        return float(os.getenv("GOOGLE_DRIVE_BOOTSTRAP_TTL_SEC", "300") or 300)
+
+    def _apply_bootstrap_payload(self, payload: dict[str, Any]) -> None:
+        mappings = {
+            "shared_state_backend": "KAPO_SHARED_STATE_BACKEND",
+            "shared_state_folder_id": "GOOGLE_DRIVE_SHARED_STATE_FOLDER_ID",
+            "shared_state_prefix": "GOOGLE_DRIVE_SHARED_STATE_PREFIX",
+            "storage_folder_id": "GOOGLE_DRIVE_STORAGE_FOLDER_ID",
+            "storage_prefix": "GOOGLE_DRIVE_STORAGE_PREFIX",
+            "access_token": "GOOGLE_DRIVE_ACCESS_TOKEN",
+            "refresh_token": "GOOGLE_DRIVE_REFRESH_TOKEN",
+            "client_secret_json": "GOOGLE_DRIVE_CLIENT_SECRET_JSON",
+            "client_secret_json_base64": "GOOGLE_DRIVE_CLIENT_SECRET_JSON_BASE64",
+            "client_secret_path": "GOOGLE_DRIVE_CLIENT_SECRET_PATH",
+            "token_expires_at": "GOOGLE_DRIVE_TOKEN_EXPIRES_AT",
+            "firebase_enabled": "FIREBASE_ENABLED",
+            "executor_url": "EXECUTOR_URL",
+            "executor_public_url": "EXECUTOR_PUBLIC_URL",
+            "ngrok_authtoken": "NGROK_AUTHTOKEN",
+            "brain_public_url": "BRAIN_PUBLIC_URL",
+            "brain_roles": "BRAIN_ROLES",
+            "brain_languages": "BRAIN_LANGUAGES",
+        }
+        for key, env_name in mappings.items():
+            value = payload.get(key)
+            if value not in (None, ""):
+                os.environ[env_name] = str(value)
+
+    def ensure_bootstrap_loaded(self, force: bool = False) -> dict[str, Any]:
+        bootstrap_url = self._bootstrap_url()
+        if not bootstrap_url:
+            return {}
+        now = time.time()
+        if not force and self._bootstrap_payload and (now - self._bootstrap_loaded_at) < self._bootstrap_ttl():
+            return dict(self._bootstrap_payload)
+        with self._bootstrap_lock:
+            now = time.time()
+            if not force and self._bootstrap_payload and (now - self._bootstrap_loaded_at) < self._bootstrap_ttl():
+                return dict(self._bootstrap_payload)
+            try:
+                response = requests.get(bootstrap_url, timeout=20)
+                response.raise_for_status()
+                payload = dict(response.json() or {})
+                self._bootstrap_payload = payload
+                self._bootstrap_loaded_at = time.time()
+                self._apply_bootstrap_payload(payload)
+                return dict(payload)
+            except Exception:
+                self.logger.warning("Failed to load Google Drive bootstrap manifest", exc_info=True)
+                return dict(self._bootstrap_payload)
+
+    def enabled(self) -> bool:
+        self.ensure_bootstrap_loaded()
+        return bool(self.root_folder_id())
+
+    def root_folder_id(self) -> str:
+        return str(
+            os.getenv("GOOGLE_DRIVE_SHARED_STATE_FOLDER_ID", "")
+            or os.getenv("GOOGLE_DRIVE_STORAGE_FOLDER_ID", "")
+            or ""
+        ).strip()
+
+    def prefix(self) -> str:
+        return str(
+            os.getenv("GOOGLE_DRIVE_SHARED_STATE_PREFIX", "")
+            or os.getenv("GOOGLE_DRIVE_STORAGE_PREFIX", "")
+            or "kapo/shared_state"
+        ).strip("/ ")
+
+    def _control_plane_token(self, label: str) -> str:
+        candidates = [
+            Path.cwd().resolve() / "data" / "local" / "control_plane.db",
+            Path.cwd().resolve() / "data" / "drive_cache" / "control_plane.db",
+        ]
+        for db_path in candidates:
+            if not db_path.exists():
+                continue
+            try:
+                conn = sqlite3.connect(db_path)
+                conn.row_factory = sqlite3.Row
+                row = conn.execute(
+                    "SELECT token FROM ngrok_tokens WHERE label = ? AND enabled = 1",
+                    (label,),
+                ).fetchone()
+                conn.close()
+                token = str(row["token"]) if row else ""
+                if token:
+                    return token
+            except Exception:
+                self.logger.warning("Failed to read Google Drive token from %s", db_path, exc_info=True)
+        return ""
+
+    def _client_secret_payload(self) -> dict[str, Any] | None:
+        raw = str(os.getenv("GOOGLE_DRIVE_CLIENT_SECRET_JSON", "")).strip()
+        raw_b64 = str(os.getenv("GOOGLE_DRIVE_CLIENT_SECRET_JSON_BASE64", "")).strip()
+        path = str(os.getenv("GOOGLE_DRIVE_CLIENT_SECRET_PATH", "")).strip()
+        if raw:
+            try:
+                return json.loads(raw)
+            except Exception:
+                self.logger.warning("Invalid GOOGLE_DRIVE_CLIENT_SECRET_JSON", exc_info=True)
+        if raw_b64:
+            try:
+                return json.loads(base64.b64decode(raw_b64).decode("utf-8"))
+            except Exception:
+                self.logger.warning("Invalid GOOGLE_DRIVE_CLIENT_SECRET_JSON_BASE64", exc_info=True)
+        if path:
+            try:
+                return json.loads(Path(path).expanduser().read_text(encoding="utf-8"))
+            except Exception:
+                self.logger.warning("Failed to load Google Drive client secret path %s", path, exc_info=True)
+        client_id = str(os.getenv("GOOGLE_DRIVE_CLIENT_ID", "")).strip()
+        client_secret = str(os.getenv("GOOGLE_DRIVE_CLIENT_SECRET", "")).strip()
+        token_uri = str(os.getenv("GOOGLE_DRIVE_TOKEN_URI", "https://oauth2.googleapis.com/token")).strip()
+        if client_id and client_secret:
+            return {
+                "installed": {
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "token_uri": token_uri,
+                }
+            }
+        return None
+
+    def _oauth_client(self) -> dict[str, str]:
+        payload = self._client_secret_payload() or {}
+        installed = payload.get("installed") or payload.get("web") or {}
+        return {
+            "client_id": str(installed.get("client_id") or "").strip(),
+            "client_secret": str(installed.get("client_secret") or "").strip(),
+            "token_uri": str(installed.get("token_uri") or "https://oauth2.googleapis.com/token").strip(),
+        }
+
+    def _refresh_token(self) -> str:
+        return str(os.getenv("GOOGLE_DRIVE_REFRESH_TOKEN", "") or self._control_plane_token("google_drive_refresh_token") or "").strip()
+
+    def _access_token(self) -> str:
+        token = str(os.getenv("GOOGLE_DRIVE_ACCESS_TOKEN", "") or self._control_plane_token("google_drive_access_token") or "").strip()
+        expires_at = float(str(os.getenv("GOOGLE_DRIVE_TOKEN_EXPIRES_AT", "0") or "0") or 0)
+        if token and (not expires_at or expires_at > (time.time() + 60)):
+            return token
+        refreshed = self._refresh_access_token()
+        return refreshed or token
+
+    def _refresh_access_token(self) -> str:
+        refresh_token = self._refresh_token()
+        client = self._oauth_client()
+        if not refresh_token or not client["client_id"] or not client["client_secret"]:
+            return ""
+        response = requests.post(
+            client["token_uri"],
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": client["client_id"],
+                "client_secret": client["client_secret"],
+            },
+            timeout=30,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        access_token = str(payload.get("access_token") or "").strip()
+        expires_in = float(payload.get("expires_in") or 0)
+        if access_token:
+            os.environ["GOOGLE_DRIVE_ACCESS_TOKEN"] = access_token
+            os.environ["GOOGLE_DRIVE_TOKEN_EXPIRES_AT"] = str(time.time() + expires_in) if expires_in else "0"
+        return access_token
+
+    def _request(self, method: str, url: str, *, headers: dict[str, str] | None = None, timeout: int = 60, **kwargs) -> requests.Response:
+        token = self._access_token()
+        if not token:
+            raise ValueError("Google Drive access token is not configured")
+        base_headers = dict(headers or {})
+        response: requests.Response | None = None
+        for _ in range(2):
+            response = requests.request(
+                method,
+                url,
+                headers={**base_headers, "Authorization": f"Bearer {token}"},
+                timeout=timeout,
+                **kwargs,
+            )
+            if response.status_code != 401:
+                response.raise_for_status()
+                return response
+            token = self._refresh_access_token()
+            if not token:
+                break
+        assert response is not None
+        response.raise_for_status()
+        return response
+
+    @staticmethod
+    def _escape_query(value: str) -> str:
+        return str(value or "").replace("\\", "\\\\").replace("'", "\\'")
+
+    def _find_folder(self, name: str, parent_id: str) -> str:
+        query = (
+            "mimeType = 'application/vnd.google-apps.folder' and trashed = false "
+            f"and name = '{self._escape_query(name)}'"
+        )
+        if parent_id:
+            query += f" and '{self._escape_query(parent_id)}' in parents"
+        response = self._request(
+            "GET",
+            "https://www.googleapis.com/drive/v3/files",
+            params={"q": query, "fields": "files(id,name)", "pageSize": 10, "supportsAllDrives": "true"},
+        )
+        files = response.json().get("files", [])
+        return str(files[0].get("id") or "").strip() if files else ""
+
+    def _create_folder(self, name: str, parent_id: str) -> str:
+        payload: dict[str, Any] = {"name": name, "mimeType": "application/vnd.google-apps.folder"}
+        if parent_id:
+            payload["parents"] = [parent_id]
+        response = self._request(
+            "POST",
+            "https://www.googleapis.com/drive/v3/files?supportsAllDrives=true",
+            headers={"Content-Type": "application/json; charset=UTF-8"},
+            json=payload,
+        )
+        return str(response.json().get("id") or "").strip()
+
+    def _ensure_folder_path(self, relative_path: str) -> str:
+        current_parent = self.root_folder_id()
+        parts = [part for part in f"{self.prefix()}/{relative_path}".replace("\\", "/").split("/") if part.strip()]
+        for part in parts:
+            safe_part = _safe_name(part, "folder")
+            cache_key = f"{current_parent}:{safe_part}"
+            cached = self._folder_cache.get(cache_key)
+            if cached:
+                current_parent = cached
+                continue
+            folder_id = self._find_folder(safe_part, current_parent)
+            if not folder_id:
+                folder_id = self._create_folder(safe_part, current_parent)
+            self._folder_cache[cache_key] = folder_id
+            current_parent = folder_id
+        return current_parent
+
+    def _find_file(self, folder_id: str, file_name: str) -> str:
+        cache_key = f"{folder_id}:{file_name}"
+        cached = self._file_cache.get(cache_key)
+        if cached:
+            return cached
+        query = (
+            "trashed = false "
+            f"and name = '{self._escape_query(file_name)}' "
+            f"and '{self._escape_query(folder_id)}' in parents"
+        )
+        response = self._request(
+            "GET",
+            "https://www.googleapis.com/drive/v3/files",
+            params={"q": query, "fields": "files(id,name)", "pageSize": 10, "supportsAllDrives": "true"},
+        )
+        files = response.json().get("files", [])
+        file_id = str(files[0].get("id") or "").strip() if files else ""
+        if file_id:
+            self._file_cache[cache_key] = file_id
+        return file_id
+
+    def _create_file(self, folder_id: str, file_name: str) -> str:
+        response = self._request(
+            "POST",
+            "https://www.googleapis.com/drive/v3/files?supportsAllDrives=true",
+            headers={"Content-Type": "application/json; charset=UTF-8"},
+            json={"name": file_name, "parents": [folder_id]},
+        )
+        file_id = str(response.json().get("id") or "").strip()
+        if file_id:
+            self._file_cache[f"{folder_id}:{file_name}"] = file_id
+        return file_id
+
+    def _upload_json(self, file_id: str, payload: dict[str, Any]) -> None:
+        self._request(
+            "PATCH",
+            f"https://www.googleapis.com/upload/drive/v3/files/{file_id}?uploadType=media&supportsAllDrives=true",
+            headers={"Content-Type": "application/json; charset=UTF-8"},
+            data=json.dumps(payload, ensure_ascii=False, sort_keys=True).encode("utf-8"),
+        )
+
+    def _download_json(self, file_id: str) -> dict[str, Any]:
+        response = self._request(
+            "GET",
+            f"https://www.googleapis.com/drive/v3/files/{file_id}?alt=media&supportsAllDrives=true",
+        )
+        return dict(response.json() or {})
+
+    def get_document(self, collection: str, doc_id: str) -> dict[str, Any]:
+        if not self.enabled():
+            return {}
+        folder_id = self._ensure_folder_path(_safe_name(collection, "collection"))
+        file_name = f"{_safe_name(doc_id)}.json"
+        file_id = self._find_file(folder_id, file_name)
+        if not file_id:
+            return {}
+        try:
+            payload = self._download_json(file_id)
+            payload.setdefault("id", _safe_name(doc_id))
+            return payload
+        except Exception:
+            self.logger.warning("Failed to download shared-state file %s/%s", collection, doc_id, exc_info=True)
+            return {}
+
+    def set_document(self, collection: str, doc_id: str, payload: dict[str, Any], *, merge: bool = True) -> bool:
+        if not self.enabled():
+            return False
+        safe_doc = _safe_name(doc_id)
+        try:
+            existing = self.get_document(collection, safe_doc) if merge else {}
+            combined = {**existing, **dict(payload or {})} if merge else dict(payload or {})
+            combined.setdefault("id", safe_doc)
+            folder_id = self._ensure_folder_path(_safe_name(collection, "collection"))
+            file_name = f"{safe_doc}.json"
+            file_id = self._find_file(folder_id, file_name)
+            if not file_id:
+                file_id = self._create_file(folder_id, file_name)
+            self._upload_json(file_id, combined)
+            return True
+        except Exception:
+            self.logger.warning("Failed to upload shared-state file %s/%s", collection, safe_doc, exc_info=True)
+            return False
+
+    def list_documents(self, collection: str, *, limit: int = 200) -> list[dict[str, Any]]:
+        if not self.enabled():
+            return []
+        try:
+            folder_id = self._ensure_folder_path(_safe_name(collection, "collection"))
+            query = f"trashed = false and '{self._escape_query(folder_id)}' in parents"
+            response = self._request(
+                "GET",
+                "https://www.googleapis.com/drive/v3/files",
+                params={
+                    "q": query,
+                    "fields": "files(id,name,modifiedTime)",
+                    "pageSize": max(1, int(limit)),
+                    "supportsAllDrives": "true",
+                    "orderBy": "modifiedTime desc",
+                },
+            )
+            items: list[dict[str, Any]] = []
+            for file in response.json().get("files", []):
+                file_id = str(file.get("id") or "").strip()
+                file_name = str(file.get("name") or "").strip()
+                if not file_id or not file_name.endswith(".json"):
+                    continue
+                self._file_cache[f"{folder_id}:{file_name}"] = file_id
+                payload = self._download_json(file_id)
+                payload.setdefault("id", file_name[:-5])
+                items.append(payload)
+            return items
+        except Exception:
+            self.logger.warning("Failed to list shared-state collection %s", collection, exc_info=True)
+            return []
+
+    def delete_document(self, collection: str, doc_id: str) -> bool:
+        if not self.enabled():
+            return False
+        safe_doc = _safe_name(doc_id)
+        try:
+            folder_id = self._ensure_folder_path(_safe_name(collection, "collection"))
+            file_name = f"{safe_doc}.json"
+            file_id = self._find_file(folder_id, file_name)
+            if not file_id:
+                return True
+            self._request(
+                "DELETE",
+                f"https://www.googleapis.com/drive/v3/files/{file_id}?supportsAllDrives=true",
+            )
+            self._file_cache.pop(f"{folder_id}:{file_name}", None)
+            return True
+        except Exception:
+            self.logger.warning("Failed to delete shared-state file %s/%s", collection, safe_doc, exc_info=True)
+            return False

shared/remote_env.py

@@ -0,0 +1,102 @@
+"""Encrypted remote .env loader and publisher helpers."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import logging
+import os
+from typing import Any
+
+import requests
+from cryptography.fernet import Fernet
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from dotenv import dotenv_values
+
+
+def _decode_maybe_b64(value: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return ""
+    try:
+        padded = text + "=" * (-len(text) % 4)
+        decoded = base64.urlsafe_b64decode(padded.encode("utf-8")).decode("utf-8")
+        if decoded:
+            return decoded
+    except Exception:
+        pass
+    return text
+
+
+def _derive_key(password: str, salt: bytes) -> bytes:
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=390000,
+    )
+    return base64.urlsafe_b64encode(kdf.derive(password.encode("utf-8")))
+
+
+def build_remote_env_bundle(env_text: str, password: str, metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+    salt = os.urandom(16)
+    key = _derive_key(password, salt)
+    token = Fernet(key).encrypt((env_text or "").encode("utf-8"))
+    return {
+        "schema": "kapo-remote-env-v1",
+        "salt": base64.urlsafe_b64encode(salt).decode("utf-8"),
+        "token": token.decode("utf-8"),
+        "metadata": dict(metadata or {}),
+    }
+
+
+def decrypt_remote_env_bundle(payload: dict[str, Any], password: str) -> str:
+    salt_raw = str(payload.get("salt") or "").strip()
+    token = str(payload.get("token") or "").strip()
+    if not salt_raw or not token:
+        raise ValueError("Remote env payload is incomplete")
+    salt = base64.urlsafe_b64decode(salt_raw.encode("utf-8"))
+    key = _derive_key(password, salt)
+    return Fernet(key).decrypt(token.encode("utf-8")).decode("utf-8")
+
+
+def _remote_env_url() -> str:
+    return _decode_maybe_b64(
+        str(os.getenv("KAPO_REMOTE_ENV_URL", "") or os.getenv("KAPO_REMOTE_ENV_URL_B64", "") or "").strip()
+    )
+
+
+def _remote_env_password() -> str:
+    return _decode_maybe_b64(
+        str(os.getenv("KAPO_REMOTE_ENV_PASSWORD", "") or os.getenv("KAPO_REMOTE_ENV_PASSWORD_B64", "") or "").strip()
+    )
+
+
+def load_remote_env_if_configured(*, override: bool = True, logger_name: str = "kapo.remote_env") -> dict[str, str]:
+    logger = logging.getLogger(logger_name)
+    if str(os.getenv("KAPO_REMOTE_ENV_LOADED", "")).strip().lower() in {"1", "true", "yes", "on"}:
+        return {}
+    url = _remote_env_url()
+    password = _remote_env_password()
+    if not url or not password:
+        return {}
+    try:
+        response = requests.get(url, timeout=30)
+        response.raise_for_status()
+        payload = dict(response.json() or {})
+        env_text = decrypt_remote_env_bundle(payload, password)
+        parsed = {
+            str(key): str(value)
+            for key, value in dotenv_values(stream=io.StringIO(env_text)).items()
+            if key and value is not None
+        }
+        for key, value in parsed.items():
+            if override or key not in os.environ or not str(os.getenv(key) or "").strip():
+                os.environ[key] = value
+        os.environ["KAPO_REMOTE_ENV_LOADED"] = "1"
+        return parsed
+    except Exception:
+        logger.warning("Failed to load encrypted remote env bundle", exc_info=True)
+        return {}