Upload 58 files

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* 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
+app/db/skills/core/core.db filter=lfs diff=lfs merge=lfs -text

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [volkansah]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: volkansah
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/scripts/generate_structure.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+# =============================================================================
+# generate_structure.py
+# Generates PROJECT_STRUCTURE.md with a visual repo tree.
+# Place in: .codey/scripts/generate_structure.py
+# =============================================================================
+# PYTHON VERSION NOTE:
+#   Embedding \n inside f-string expressions like f"{'\n'.join(x)}" is only
+#   supported from Python 3.12+. On 3.10/3.11 (GitHub Actions default) this
+#   causes a SyntaxError: "unterminated string literal".
+#   FIX: always build the joined string BEFORE the f-string block.
+#   Example:
+#       BAD  → f"```\n{'\n'.join(tree)}\n```"   # crashes on 3.10/3.11
+#       GOOD → tree_str = "\n".join(tree)
+#              then use tree_str inside f-string or concatenation
+# =============================================================================
+
+from pathlib import Path
+from datetime import datetime
+
+# ─────────────────────────────────────────────
+# IGNORE LIST — folders/files to skip
+# ─────────────────────────────────────────────
+IGNORE = {
+    '.git',
+    '__pycache__',
+    '.pytest_cache',
+    '*.pyc',
+    '.DS_Store',
+    'node_modules',
+    '.venv',
+    'venv',
+}
+
+def is_ignored(path: Path) -> bool:
+    name = path.name
+    for pattern in IGNORE:
+        if '*' in pattern:
+            if path.match(pattern):
+                return True
+        elif name == pattern:
+            return True
+    return False
+
+
+def generate_tree(root: Path, prefix: str = "", is_last: bool = True) -> list:
+    lines     = []
+    connector = "└── " if is_last else "├── "
+
+    if root == Path("."):
+        lines.append(root.resolve().name + "/")
+        children = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        visible  = [c for c in children if not is_ignored(c)]
+        for i, child in enumerate(visible):
+            lines.extend(generate_tree(child, prefix="", is_last=(i == len(visible) - 1)))
+        return lines
+
+    if root.is_dir():
+        lines.append(f"{prefix}{connector}{root.name}/")
+        extension = "    " if is_last else "│   "
+        children  = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+        visible   = [c for c in children if not is_ignored(c)]
+        for i, child in enumerate(visible):
+            lines.extend(generate_tree(child, prefix + extension, is_last=(i == len(visible) - 1)))
+    else:
+        lines.append(f"{prefix}{connector}{root.name}")
+
+    return lines
+
+
+def main():
+    root = Path(".")
+    tree = generate_tree(root)
+    now  = datetime.utcnow().strftime("%Y-%m-%d %H:%M UTC")
+
+    # Build tree string BEFORE f-string — required for Python < 3.12
+    tree_str = "\n".join(tree)
+
+    output  = "# 📁 Project Structure\n\n"
+    output += f"> Auto-generated by `generate_structure.py` — {now}\n"
+    output += "> Do not edit manually.\n\n"
+    output += "```\n"
+    output += tree_str + "\n"
+    output += "```\n"
+
+    out_path = Path("PROJECT_STRUCTURE.md")
+    out_path.write_text(output, encoding="utf-8")
+    print(f"✓ PROJECT_STRUCTURE.md written ({len(tree)} lines)")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/clean_repo.example

@@ -0,0 +1,61 @@
+name: Clean Slate (Custom Keep List)
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  wipe-repo:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Rebuild Clean Branch with Whitelist
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # 1. Orphan Branch ohne Historie erstellen
+          git checkout --orphan temp-clean-slate
+          
+          # 2. Nur den Git-Index leeren (Festplatte bleibt unangetastet)
+          git read-tree --empty
+          
+          # =================================================================
+          # WHITELIST: Hier definierst du, was ERHALTEN bleiben soll.
+          # Nicht benötigte Zeilen einfach mit # auskommentieren!
+          # =================================================================
+          
+          # Core / Infrastructure
+          [ -e .github ] && git add .github/
+          [ -e README.md ] && git add README.md
+          [ -e .gitignore ] && git add .gitignore
+          [ -e .gitattributes ] && git add .gitattributes
+          
+          # Documentation & Legal
+          [ -e LICENSE ] && git add LICENSE
+          [ -e SECURITY.md ] && git add SECURITY.md
+          [ -e STATUS.md ] && git add STATUS.md
+          [ -e CONTRIBUTING.md ] && git add CONTRIBUTING.md
+          [ -e CODE_OF_CONDUCT.md ] && git add CODE_OF_CONDUCT.md
+          [ -e CITATION.cff ] && git add CITATION.cff
+          
+          # Individuelle Ergänzungen 
+          # [ -e .pyfun ] && git add .pyfun
+          # =================================================================
+          
+          # 3. Sauberen Commit erstellen
+          git commit -m "style: reset repository keeping whitelisted core metadata"
+          
+          # 4. Lokalen main-Branch durch den sauberen Branch ersetzen
+          git branch -D main
+          git branch -m main
+
+      - name: Force Push to Main
+        run: |
+          git push origin main --force

.github/workflows/generate_structure.example

@@ -0,0 +1,56 @@
+# =============================================================================
+# WORKFLOW: Generate Repo Structure - [Generate Repo Structure]
+# PART OF:  Codey - No Mercy EDITION
+# =============================================================================
+# Role:        Automated Audit & Compliance (ESOL v1.1)
+# Copyright:   (c) 2026 VolkanSah
+# License:     Apache 2.0 + ESOL v1.1 (https://github.com/VolkanSah/ESOL)
+# Enforcement: Jurisdiction Berlin, Germany (StGB & DSGVO)
+# =============================================================================
+
+# Name of the workflow used to visualize the file hierarchy
+name: Generate Repo Structure
+
+# Trigger: Manual execution only (allows the dev to choose when to update the map)
+on:
+  workflow_dispatch:
+
+# Permissions: Granting write access so the bot can save the generated Markdown
+permissions:
+  contents: write
+
+jobs:
+  # Job to analyze and map the directory tree
+  structure:
+    # Running on the latest stable Ubuntu environment
+    runs-on: ubuntu-latest
+    steps:
+      # Step 1: Pull the latest code using a custom token
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GIT_TOKEN_AIHUB }}
+
+      # Step 2: Prepare Python for the generator script
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      # Step 3: Run the custom logic that scans directories and creates PROJECT_STRUCTURE.md
+      - name: Generate structure
+        run: python .github/scripts/generate_structure.py
+
+      # Step 4: Finalize by pushing the new "Map" to the repository root
+      - name: Commit structure
+        run: |
+          # Identity setup for the automated commit
+          git config user.name  "Codey Bot"
+          git config user.email "codey@bot"
+          
+          # Stage the specific file generated by the script
+          git add PROJECT_STRUCTURE.md
+          
+          # Check for changes to prevent empty commits; [skip ci] avoids re-triggering workflows
+          git diff --staged --quiet || git commit -m "📁 update project structure [skip ci]"
+          
+          # Push the updated structure map back to the origin
+          git push

.gitignore

@@ -1,19 +1,12 @@
-# Universal-MCP-server-sandox
-
-README.MD
-.gitignore
-app/*
-
-
-
-
-
 
 .env
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[codz]
 *$py.class
+mcp_desktop.json
+DESKTOP_UI/mcp_desktop.json
+
 
 
 # C extensions
@@ -218,3 +211,12 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# --- Hub: Secrets / lokaler State — NIE committen ---
+DESKTOP_UI/mcp_desktop.json
+mcp_desktop.json
+app/.hub_state.db
+app/cms_database.db
+# Skill-DBs (app/db/skills/**/*.db) werden committet, WAL/SHM-Begleitdateien nicht
+*.db-wal
+*.db-shm

CITATION.cff

@@ -0,0 +1,9 @@
+cff-version: 1.2.0
+message: "If you use Universal MCP HUB in your security research, please cite it as follows."
+authors:
+- family-names: "Kücükbudak"
+  given-names: "Volkan"
+title: "Universal MCP Hub (Sandboxed)"
+version: 0.0.1
+date-released: 2026-03-09
+url: "https://github.com/VolkanSah/Universal-MCP-Hub/"

CODE_OF_CONDUCT.md

@@ -0,0 +1,68 @@
+# Code of Conduct
+
+## The Short Version
+
+Build things that work. Understand what you ship. Don't use this to harm people.
+
+---
+
+## What This Project Stands For
+
+The MCP ecosystem is full of servers built for the demo, not for production. Hardcoded keys, zero sandboxing, `os.environ` everywhere — and nobody reads the code before forking it.
+
+This project exists as a counter-example. The goal is not to be the most popular MCP server. The goal is to be one that people can actually trust — and learn from.
+
+That shapes what kind of community belongs here.
+
+---
+
+## What We Expect
+
+**Understand before you contribute.**  
+Read the architecture. Understand why `app/*` can't touch `fundaments/`. Understand why there are two databases. If something seems over-engineered, ask first — there's usually a reason.
+
+**Security is not optional.**  
+Don't submit PRs that weaken the sandbox, expose secrets through new code paths, or add convenience features that bypass the Guardian pattern. If you think a security boundary is wrong, open an issue and argue the case — don't just route around it.
+
+**AI is a tool, not a co-author.**  
+Using AI to help write code, docs, or tests is fine. Submitting AI-generated code you don't understand is not. You are responsible for what you put your name on. If you can't explain it in a code review, it doesn't belong here.
+
+**Be direct, not brutal.**  
+Bad code should be called bad code. Vague encouragement helps nobody. But there's a difference between "this approach has a security problem because..." and being dismissive. Explain the problem. Propose a fix. Move on.
+
+**No hype, no growth-hacking.**  
+Don't open issues asking to add integrations just because they're trending. Don't submit PRs that add features nobody asked for to pad a portfolio. This is a security-focused project — new features get scrutinized for attack surface, not applauded for volume.
+
+---
+
+## What We Don't Tolerate
+
+- Using this project to harm, surveil, or exploit others — the [ESOL v1.1](ESOL) license makes this automatic grounds for termination of all rights
+- Submitting intentionally malicious code, backdoors, or obfuscated logic
+- Harassment, discrimination, or personal attacks — in issues, PRs, or discussions
+- Deliberate misrepresentation of how the code works in documentation or comments
+
+---
+
+## On Contributing
+
+Before opening a PR:
+
+1. Open an issue first for anything non-trivial — discuss the approach before writing the code
+2. Make sure your change doesn't break the sandbox rules (see [SECURITY.md](SECURITY.md))
+3. Write code you'd be comfortable explaining line by line in a review
+4. If you add a provider, add the dummy class pattern — future contributors will thank you
+
+Small, focused PRs get reviewed faster than large ones. A PR that fixes one thing well is worth more than one that does five things loosely.
+
+---
+
+## Enforcement
+
+Violations of the ethical use constraints in ESOL v1.1 are reported to the author directly and, where appropriate, to relevant authorities. There's no three-strikes policy for deliberate misuse.
+
+For everything else — bad behavior in the community, violations of the conduct guidelines above — the maintainer will handle it case by case. The goal is to keep the project useful and trustworthy, not to maintain a leaderboard of infractions.
+
+---
+
+*This project was built by someone who wanted to understand how things actually work — not how they look in a README. That's the kind of contributor who belongs here.*

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing to Universal MCP Hub
+
+Thanks for considering a contribution. Read this before opening a PR.
+
+---
+
+## Before You Start
+
+Open an issue first for anything non-trivial. Describe what you want to change and why. This avoids situations where you spend time on a PR that conflicts with the architecture or is out of scope.
+
+For typos, doc fixes, or obvious bugs — just open the PR directly.
+
+---
+
+## The Non-Negotiables
+
+These rules are not up for debate in PRs. If you disagree with them, open an issue and make the case.
+
+**1. Don't break the sandbox.**  
+`app/*` must never import from `fundaments/`, read `os.environ`, or access `.env` directly. The Guardian pattern (`main.py` injects services, `app/*` receives them) is the core security guarantee of this project. PRs that route around it will be closed.
+
+**2. No secrets in code or config.**  
+`app/.pyfun` references ENV variable names only — never values. If your PR puts an API key, token, or credential anywhere in the codebase, it gets closed immediately.
+
+**3. `db_query` stays SELECT-only.**  
+The read-only enforcement in `db_sync.py` is not a suggestion. Don't submit PRs that add write access through the MCP tool layer.
+
+**4. New providers need a dummy too.**  
+If you add a new LLM or search provider, add a commented-out dummy class following the existing pattern. Future contributors should be able to add the next provider by copying your dummy.
+
+---
+
+## How to Add a New LLM Provider
+
+Three files, nothing else:
+
+**1. `app/providers.py`** — add your class (copy the OpenAI dummy as starting point):
+
+```python
+class YourProvider(BaseProvider):
+    """Your Provider API — brief description."""
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+        data = await self._post(
+            f"{self.base_url}/chat/completions",  # adjust endpoint
+            headers={
+                "Authorization": f"Bearer {self.key}",
+                "content-type":  "application/json",
+            },
+            payload={
+                "model":      model or self.model,
+                "max_tokens": max_tokens,
+                "messages":   [{"role": "user", "content": prompt}],
+            },
+        )
+        return data["choices"][0]["message"]["content"]  # adjust response parsing
+```
+
+**2. `app/providers.py`** — register in `_PROVIDER_CLASSES`:
+
+```python
+_PROVIDER_CLASSES = {
+    ...
+    "yourprovider": YourProvider,
+}
+```
+
+**3. `app/.pyfun`** — add provider block:
+
+```ini
+[LLM_PROVIDER.yourprovider]
+active        = "true"
+base_url      = "https://api.yourprovider.com/v1"
+env_key       = "YOUR_PROVIDER_API_KEY"
+default_model = "your-default-model"
+models        = "your-default-model, other-model"
+fallback_to   = ""
+[LLM_PROVIDER.yourprovider_END]
+```
+
+Then add a commented dummy of your class above the `_PROVIDER_CLASSES` dict with the `.pyfun` block as a comment — same style as OpenAI/Mistral/xAI dummies already there.
+
+Most OpenAI-compatible APIs (Mistral, xAI, Together, etc.) need zero changes to the class body — just different `base_url` and `env_key`. Providers with non-standard auth (like Gemini's `?key=` param) need their own `complete()` implementation.
+
+---
+
+## How to Add a New Search Provider
+
+Search providers follow the same pattern as LLM providers but register in `_SEARCH_REGISTRY` (not yet implemented — first search provider PR sets the pattern). Look at how `BraveProvider` and `TavilyProvider` are planned in `.pyfun` for reference.
+
+---
+
+## How to Add a New Tool
+
+Tools are defined in `app/.pyfun` under `[TOOLS]` and registered in `app/mcp.py`. A tool needs:
+
+- A `[TOOL.name]` block in `.pyfun` with `provider_type`, `default_provider`, `system_prompt` (for LLM tools)
+- Registration in `mcp.py` via the appropriate `_register_*_tools()` function
+- Execution logic in `app/tools.py`
+
+Tools that require an API key must gate their registration — if the key isn't set, the tool must not register. No key, no tool, no crash. See existing tool registration in `mcp.py` for the pattern.
+
+---
+
+## Code Style
+
+- Match the existing style — same header format, same section separators, same logging pattern
+- One logger per module: `logger = logging.getLogger("module_name")`
+- Async where the code is already async (`app/*`), sync where it's sync (`fundaments/*`)
+- Comments explain *why*, not *what* — the code shows what
+
+---
+
+## Testing Your Changes
+
+Before submitting:
+
+```bash
+# install dependencies
+pip install -r requirements.txt
+
+# start with minimal config (no keys needed for basic startup test)
+python main.py
+
+# check that startup completes without errors
+# check that list_active_tools returns expected results
+# check that missing keys don't crash the server
+```
+
+If you're adding a provider: test with a real key in a local `.env`. Document the response format you're parsing from in your PR description.
+
+---
+
+## PR Checklist
+
+- [ ] Sandbox rules not broken (`app/*` has no new `os.environ` or `fundaments/` imports)
+- [ ] No credentials or secrets in any file
+- [ ] New provider includes dummy class + `.pyfun` block
+- [ ] Startup still works with zero API keys configured
+- [ ] Code follows existing style and header format
+- [ ] PR description explains what changed and why
+
+---
+
+## What Won't Be Merged
+
+- Features that add attack surface without clear security justification
+- AI-generated code the author can't explain in review
+- PRs that touch `fundaments/` without a very good reason — that layer is stable by design
+- Dependency additions without justification — the stack is intentionally lean
+
+---
+
+*Questions? Open an issue. The architecture docs in `README.md`, `SECURITY.md`, and `docs/` cover most of the "why" behind the design decisions.*

Dockerfile

@@ -18,9 +18,8 @@ RUN pip install --no-cache-dir -r requirements.txt
 # Copy the rest of the application code into the working directory.
 COPY . .
 
-# Expose a port if your application is a web server.
-# For example, if your application runs on port 8000.
-# EXPOSE 8000
+# Expose the hub port (matches HUB_PORT in app/.pyfun)
+EXPOSE 7860
 
 # Define the command to run your application.
 # This command will be executed when the container starts.

LICENSE

@@ -1,201 +1,661 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

PyFundaments #U2013 Function Overview.md

@@ -0,0 +1,145 @@
+# PyFundaments – Function Overview
+
+## `main.py`
+
+| Function                  | Description                                                                                                                                 |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initialize_fundaments()` | Asynchronously initializes services based on available environment variables. Returns a dictionary of services (`None` if not initialized). |
+| `main()`                  | Application entry point. Calls `initialize_fundaments()`, loads `app/app.py`, closes DB pool on shutdown.                                   |
+
+---
+
+## `fundaments/config_handler.py` – `ConfigHandler`
+
+| Function                 | Description                                                        |
+| ------------------------ | ------------------------------------------------------------------ |
+| `__init__()`             | Loads `.env` via `python-dotenv` and system environment variables. |
+| `load_all_config()`      | Stores all non-empty environment variables in `self.config`.       |
+| `get(key)`               | Returns value as string or `None`.                                 |
+| `get_bool(key, default)` | Parses boolean values (`true/1/yes/on`).                           |
+| `get_int(key, default)`  | Returns integer value or `default` on failure.                     |
+| `has(key)`               | Returns `True` if key exists and is not empty.                     |
+| `get_all()`              | Returns copy of full configuration dictionary.                     |
+| `config_service`         | Global singleton instance.                                         |
+
+---
+
+## `fundaments/postgresql.py`
+
+| Function                                              | Description                                                                         |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `enforce_cloud_security(dsn_url)`                     | Enforces `sslmode=require`, applies timeouts, removes incompatible DSN options.     |
+| `mask_dsn(dsn_url)`                                   | Removes credentials from DSN for logging.                                           |
+| `ssl_runtime_check(conn)`                             | Verifies active SSL connection.                                                     |
+| `init_db_pool(dsn_url)`                               | Creates asyncpg pool (min=1, max=10) and runs SSL check.                            |
+| `close_db_pool()`                                     | Gracefully closes connection pool.                                                  |
+| `execute_secured_query(query, *params, fetch_method)` | Executes parameterized query (`fetch`, `fetchrow`, `execute`) with reconnect logic. |
+
+---
+
+## `fundaments/encryption.py` – `Encryption`
+
+| Function                               | Description                                                      |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| `generate_salt()`                      | Generates secure 16-byte hex salt.                               |
+| `__init__(master_key, salt)`           | Derives AES-256 key via PBKDF2-SHA256 (480k iterations).         |
+| `encrypt(data)`                        | Encrypts string using AES-256-GCM. Returns `{data, nonce, tag}`. |
+| `decrypt(encrypted_data, nonce, tag)`  | Decrypts data. Raises `InvalidTag` if tampered.                  |
+| `encrypt_file(source_path, dest_path)` | Encrypts file in 8192-byte chunks.                               |
+| `decrypt_file(source_path, dest_path)` | Decrypts file using stored nonce and tag.                        |
+
+---
+
+## `fundaments/access_control.py` – `AccessControl`
+
+| Function                                           | Description                          |
+| -------------------------------------------------- | ------------------------------------ |
+| `__init__(user_id)`                                | Initializes with optional user ID.   |
+| `has_permission(permission_name)`                  | Checks if user has permission.       |
+| `get_user_permissions()`                           | Returns all user permissions.        |
+| `get_user_roles()`                                 | Returns assigned roles.              |
+| `assign_role(role_id)`                             | Assigns role to user.                |
+| `remove_role(role_id)`                             | Removes role from user.              |
+| `get_all_roles()`                                  | Returns all roles.                   |
+| `get_all_permissions()`                            | Returns all permissions.             |
+| `create_role(name, description)`                   | Creates new role and returns ID.     |
+| `update_role_permissions(role_id, permission_ids)` | Replaces all permissions for a role. |
+| `get_role_permissions(role_id)`                    | Returns role permissions.            |
+
+---
+
+## `fundaments/user_handler.py`
+
+### `Database` (SQLite Wrapper)
+
+| Function                  | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `execute(query, params)`  | Executes query and commits.                       |
+| `fetchone(query, params)` | Returns single row.                               |
+| `fetchall(query, params)` | Returns all rows.                                 |
+| `close()`                 | Closes connection.                                |
+| `setup_tables()`          | Creates `users` and `sessions` tables if missing. |
+
+---
+
+### `Security` (Password Utilities)
+
+| Function                            | Description                                  |
+| ----------------------------------- | -------------------------------------------- |
+| `hash_password(password)`           | Hashes password (PBKDF2-SHA256 via passlib). |
+| `verify_password(password, hashed)` | Verifies password against hash.              |
+| `regenerate_session(session_id)`    | Generates new UUID session ID.               |
+
+---
+
+### `UserHandler`
+
+| Function                                  | Description                                            |
+| ----------------------------------------- | ------------------------------------------------------ |
+| `login(username, password, request_data)` | Authenticates user, validates state, creates session.  |
+| `logout()`                                | Removes session from DB and memory.                    |
+| `is_logged_in()`                          | Checks if active session exists.                       |
+| `is_admin()`                              | Checks session `is_admin` flag.                        |
+| `validate_session(request_data)`          | Validates session against IP and User-Agent.           |
+| `lock_account(username)`                  | Locks user account.                                    |
+| `reset_failed_attempts(username)`         | Resets failed login counter.                           |
+| `increment_failed_attempts(username)`     | Increments failed attempts and locks after 5 failures. |
+
+---
+
+## `fundaments/security.py` – `Security` (Orchestrator)
+
+| Function                                       | Description                                                           |
+| ---------------------------------------------- | --------------------------------------------------------------------- |
+| `__init__(services)`                           | Initializes with required services. Raises `RuntimeError` if missing. |
+| `user_login(username, password, request_data)` | Performs login and session validation.                                |
+| `check_permission(user_id, permission_name)`   | Delegates permission check.                                           |
+| `encrypt_data(data)`                           | Encrypts data if encryption service is available.                     |
+| `decrypt_data(encrypted_data, nonce, tag)`     | Decrypts data or returns `None` on failure.                           |
+
+---
+
+## `fundaments/debug.py` – `PyFundamentsDebug`
+
+| Function          | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| `__init__()`      | Reads debug-related environment variables.              |
+| `_setup_logger()` | Configures logging handlers.                            |
+| `run()`           | Outputs runtime diagnostics when debug mode is enabled. |
+
+---
+
+## `app/app.py`
+
+| Function                        | Description                                                           |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `start_application(fundaments)` | Receives initialized service dictionary and starts application logic. |
+
+---
+
+## Architecture Notes
+
+* `UserHandler` uses internal SQLite.
+* `AccessControl` uses PostgreSQL via `execute_secured_query`.
+* `security.py` `Security` is the orchestrator layer.
+* All services are optional.

README.md

@@ -1,23 +1,24 @@
 ---
-title: Multi-LLM API Gateway
+title: Universal AI Hub
 emoji: 🛡️
 colorFrom: indigo
 colorTo: red
 sdk: docker
 pinned: true
 license: apache-2.0
-short_description: Secure Multi-LLM Gateway — (Streamable HTTP / SSE)
+short_description: Secure Multi-HUB i craft since month
 ---
 
-# Multi-LLM API Gateway
 
-— or Universal MCP Hub (Sandboxed)  
-— or secure AI wrapper with dual interface: REST + MCP
 
-aka: a clean, secure starting point for your own projects.  
+# Universal AI Hub 🛡️
+> 🚧 **Status:** Under active development. Built strictly for private spaces with hardened anti-spam and anti-scammer guardrails. Use at your own discretion.
+
+
+aka: a clean, secure starting point for your own projects.
 Pick the description that fits your use case. They're all correct.
 
-> A production-grade **the-thing** that actually thinks about security.  
+> A **the-thing** that actually thinks about security.
 > Built on [PyFundaments](PyFundaments.md) — running on **simpleCity**.
 
 ```
@@ -27,15 +28,53 @@ No key → no tool → no crash → no exposed secrets
 > [!WARNING]
 > Most MCP servers are prompts dressed up as servers. This one has a real architecture.
 
----
-
 > [!IMPORTANT]
-> This project is under active development — always use the latest release from [Codey Lab](https://github.com/Codey-LAB/Multi-LLM-API-Gateway) *(more stable builds land here first)*.  
+> This project is under active development — always use the latest release from [Codey Lab](https://github.com/Codey-LAB/Multi-LLM-API-Gateway) *(more stable builds land here first)*.
 > This repo ([DEV](https://github.com/VolkanSah/Multi-LLM-API-Gateway)) is where the chaos happens. 🔬 A ⭐ on the repos will be cool 😙
 
 ---
 
-## Why this exists
+<details>
+<summary><b>🧠 Usernote: how this was actually built (no vibecode - or am I lying? 😄)</b></summary>
+     
+I created this code on my own. And it took a toll on me - I mean really took a toll. We're not talking about my code not working, but more like I've been looking at my own design for so long that my brain is a mess. That's when AI came into the picture - not to do the coding for me, but to help me make sense of my thoughts and organize the ideas that were already floating around in my head.
+
+So, is this something called vibecoding? **No**, it's not. Vibecoding is when you send off code without really understanding what it does, and just hope it works out. But I know exactly what's going on here - every single line, even the weird parts. I made some specific choices, like using the guardian pattern, setting up a sandbox, and creating a `.pyfun` file that's the single source of truth. I also followed the no-key-no-tool rule. These were all my decisions, made before any AI even got involved. My coding style is pretty unique, and you'll notice it as soon as you look at the source code. The AI was more like a partner that helped me out, typing fast and sometimes making mistakes that I had to fix.
+
+...or am I just making it up? Don't just listen to me, go check the code for yourself.
+
+</details>
+
+---
+
+<details>
+<summary><b>🆕 What's new in v1.2.0 — memory that survives a reboot</b></summary>
+
+> Full changelog (with proof) in [`REVIEW.md`](REVIEW.md). The short version, my words:
+
+- **Memory orchestration.** `persist_result` without `DATABASE_URL` used to throw a `RuntimeError`. Now everything lands in a restart-safe `persist_queue` in SQLite — proven: 3 entries in, reboot, 3 entries out — and a background flusher pushes them into PostgreSQL whenever the bridge is back. `persist_status` (MCP + `/api`) shows queue depth, attempts and bridge state.
+- **Auto-pricing, konsequent.** I asked whether the manual `cost_*` lines still make sense. OpenRouter FAQ, checked live: no markup, per-token = vendor list price (the ~5.5 % fee hits credit purchase, not tokens). So 34 cost lines are gone. What stays: my own models (`smollm2-360m` = 0.0 — no external source knows my own deployment). `.pyfun` values still win as override, always.
+- **ShellMaster = SECURITY LEVEL ROT.** My CLI commander for the local Quart agent (`localhost:5004`) — commands run on YOUR machine, so: local only, never on a public Space. Token lives in `.env` via `SHELLMASTER_TOKEN` (same pattern as every provider); the `.pyfun` field is only a local test fallback. `active = "false"`. Stays off until someone consciously flips it.
+- **Score slot for my filter.** `hub_results.score` exists — the hub passes it through completely uninterpreted. What's worth remembering long-term gets decided by my own filter, not by the hub. That part is my code, my rules.
+
+*Tests: 26/26 orchestration + 4/4 smoke — green.*
+
+<details>
+<summary><b>v1.1.0 (the rebuild) — older news</b></summary>
+
+- **Fixed:** `/mcp` 404 (mount middleware stripped the prefix FastMCP expects) and the missing session-manager lifespan — MCP is fully functional again.
+- **New:** **Auto model pricing** — costs fetched from the public OpenRouter models API + the LiteLLM community price list, cached in `db_sync` (24h TTL). `.pyfun [MODELS]` values win as override.
+- **New:** Brave + Tavily search providers with fallback chain — `web_search` registers as soon as `BRAVE_API_KEY` or `TAVILY_API_KEY` is set.
+- **New:** `db_query` as MCP tool (SELECT-only, app/* tables).
+- **Cleanup:** dead code removed, `requirements.txt` pins `mcp>=1.10,<2` (not `fastmcp`), LF line endings.
+
+</details>
+</details>
+
+--- 
+
+<details>
+<summary><b>❓ Why this exists</b></summary>
 
 The AI ecosystem is full of servers with hardcoded keys, `os.environ` scattered everywhere, zero sandboxing. One misconfigured fork and your API keys are gone.
 
@@ -48,11 +87,14 @@ This hub is the antidote:
 - **Graceful degradation** — No key? Tool doesn't register. Server still starts. No crash, no error, no empty `None` floating around.
 - **Single source of truth** — All tool/provider/model config lives in `app/.pyfun`. Adding a provider = edit one file. No code changes.
 
----
+</details>
+
+--- 
 
-## Two Interfaces — One Server
+<details>
+<summary><b>🔌 Two interfaces — one server</b></summary>
 
-This hub exposes **two completely independent interfaces** on the same hypercorn instance:
+Two completely independent interfaces on the same hypercorn instance:
 
 ```
 POST /api          → REST interface — for custom clients, desktop apps, CMS plugins
@@ -62,9 +104,7 @@ GET /              → Health check — uptime, status
 
 They share the same tool registry, provider config, and fallback chain. Adding a tool once makes it available on both interfaces automatically.
 
-### REST API (`/api`)
-
-Simple JSON POST — no protocol overhead, works with any HTTP client:
+**REST (`/api`)** — simple JSON POST, no protocol overhead, works with any HTTP client:
 
 ```json
 POST /api
@@ -73,25 +113,26 @@ POST /api
 
 Used by: Desktop Client (`DESKTOP_CLIENT/hub.py`), WordPress plugin, any custom integration.
 
-### MCP Interface (`/mcp`)
-
-Full MCP protocol — tool discovery, structured calls, streaming responses.
-
-**Primary transport: Streamable HTTP** (MCP spec 2025-11-25)  
-**Fallback transport: SSE** (legacy, configurable via `.pyfun`)
+**MCP (`/mcp`)** — full MCP protocol: tool discovery, structured calls, streaming responses.
 
-Configured via `HUB_TRANSPORT` in `app/.pyfun [HUB]`:
+- Primary transport: **Streamable HTTP** (MCP spec 2025-11-25)
+- Fallback transport: **SSE** (legacy, configurable via `.pyfun`)
 
 ```ini
+[HUB]
 HUB_TRANSPORT = "streamable-http"   # default — MCP spec 2025-11-25
 # HUB_TRANSPORT = "sse"             # legacy fallback for older clients
+[HUB_END]
 ```
 
-Used by: Claude Desktop, Cursor, Windsurf, any MCP-compatible client.
+Auth, rate limiting and logging can all hook into the `/mcp` route in `app/app.py` before a request ever reaches FastMCP.
+
+</details>
 
 ---
 
-## Architecture
+<details>
+<summary><b>🏗 Architecture — the sandbox is structural</b></summary>
 
 ```
 main.py (Guardian)
@@ -110,13 +151,13 @@ main.py (Guardian)
      ├── app/tools.py       ← Tool registry (key-gated)
      ├── app/providers.py   ← LLM + Search execution + fallback chain
      ├── app/models.py      ← Model limits, costs, capabilities
+     ├── app/shellmaster.py ← CLI commander (SECURITY LEVEL ROT — local only)
+     ├── app/pricing.py     ← Auto model pricing (OpenRouter + LiteLLM)
      ├── app/config.py      ← .pyfun parser (single source of truth)
-     └── app/db_sync.py     ← Internal SQLite IPC (app/* state only)
-                              ≠ fundaments/postgresql.py (Guardian-only)
+     └── app/db_sync.py     ← SQLite: short-term state + persist_queue (memory bridge)
+                              ≠ fundaments/postgresql.py (Guardian-only, long-term)
 ```
 
-**The sandbox is structural:**
-
 ```python
 # app/app.py — fundaments unpacked ONCE, NEVER stored globally
 async def start_application(fundaments: Dict[str, Any]) -> None:
@@ -129,61 +170,59 @@ async def start_application(fundaments: Dict[str, Any]) -> None:
     # fundaments are never passed into other app/* modules.
 ```
 
-`app/app.py` never calls `os.environ`. Never imports from `fundaments/`. Never reads `.env`.  
+`app/app.py` never calls `os.environ`. Never imports from `fundaments/`. Never reads `.env`.
 This isn't documentation. It's enforced by the import structure.
 
-### Why Quart + hypercorn?
+**Why Quart + hypercorn?**
 
 **Quart** is async Flask — fully `async/await` native. FastMCP's handlers are async; mixing sync Flask would require thread hacks. With Quart, `/mcp` hands off directly to FastMCP — no bridging, no blocking.
 
-**hypercorn** is an ASGI server (vs. waitress/gunicorn which are WSGI). WSGI servers handle one request per thread — wrong for long-lived MCP connections. hypercorn handles both Streamable HTTP and SSE natively, and runs without extra config on HuggingFace Spaces. HTTP/2 support (`config.h2 = True`) is built-in — relevant for Streamable HTTP performance at scale.
+**hypercorn** is an ASGI server (vs. waitress/gunicorn which are WSGI). WSGI servers handle one request per thread — wrong for long-lived MCP connections. hypercorn handles both Streamable HTTP and SSE natively, and runs without extra config on HuggingFace Spaces. HTTP/2 support (`config.h2 = True`) is built-in.
+
+</details>
 
-The `/mcp` route in `app.py` remains the natural interception point regardless of transport — auth checks, rate limiting, and logging can all be added there before the request reaches FastMCP.
 
 ---
 
-## Two Databases — One Architecture
+<details>
+<summary><b>💾 Memory — short-term, long-term, and my filter (v1.2.0)</b></summary>
 
+The design is deliberately simple:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│  Guardian Layer (fundaments/*)                              │
-│                                                             │
-│  postgresql.py   → Cloud DB (e.g. Neon, Supabase)          │
-│                    asyncpg pool, SSL enforced               │
-│                                                             │
-│  user_handler.py → SQLite (users + sessions tables)        │
-│                    PBKDF2-SHA256 password hashing           │
-│                    Session validation incl. IP + UserAgent  │
-│                    Account lockout after 5 failed attempts  │
-│                                                             │
-└──────────────────────┬──────────────────────────────────────┘
-                       │ inject as fundaments dict
-                       ▼
-┌─────────────────────────────────────────────────────────────┐
-│  App Layer (app/*)                                          │
-│                                                             │
-│  db_sync.py  → SQLite (hub_state + tool_cache tables)      │
-│                aiosqlite (async, non-blocking)              │
-│                NEVER touches users/sessions tables          │
-│                Relocated to /tmp/ on HF Spaces auto        │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
+SQLite  = short-term memory  — all AI tools read & write here, nobody waits for the cloud
+SQLite persist_queue = the bridge — restart-safe, survives reboots (proven)
+PostgreSQL = long-term memory — what survived MY filter goes here
+```
+
 ```
+persist_result (MCP + /api)
+   ↓ enqueue_persist()        ← immediately, ALWAYS, no crash — even without DATABASE_URL
+persist_queue (SQLite)        ← survives restarts; on HF Spaces /tmp, PG is the only durable memory
+   ↓ flush_persist_queue()    ← background flusher, retry every 60 s (configurable)
+PostgreSQL hub_results        ← (id, created_at, source, model, score, payload JSONB)
+```
+
+- **No `DATABASE_URL`?** `status: "queued"` — no RuntimeError, no 502, nothing lost.
+- **PostgreSQL down?** Entry stays, `attempts` +1, sanitized `last_error`. Flusher catches up when the bridge returns.
+- **`score REAL`** — a reserved slot for my own quality filter. The hub passes it through untouched; the filter writes it (or filters on read) later. No hub code interprets it. That's on purpose — my filter, my rules.
+- **Limits:** queue max 500 (oldest evicted, like `tool_cache`) · at-least-once semantics (a duplicate beats a loss) · observability via `persist_status` (queue depth, oldest entry, attempts, bridge state).
 
-**Table ownership — hard rule:**
+**Guardian layer vs app layer — table ownership, hard rule:**
 
 | Table | Owner | Access |
 | :--- | :--- | :--- |
 | `users` | `fundaments/user_handler.py` | Guardian only |
 | `sessions` | `fundaments/user_handler.py` | Guardian only |
-| `hub_state` | `app/db_sync.py` | app/* only |
-| `tool_cache` | `app/db_sync.py` | app/* only |
-| `hub_results` | PostgreSQL / Guardian | via `persist_result` tool |
+| `hub_state`, `tool_cache`, `persist_queue` | `app/db_sync.py` | app/* only |
+| `hub_results` | PostgreSQL / Guardian | via `persist_result` → queue → flusher |
+
+</details>
 
 ---
 
-## Tools
+<details>
+<summary><b>🧰 Tools — no key, no tool, server still starts</b></summary>
 
 Tools register at startup — only if the required API key exists. No key, no tool. Server always starts.
 
@@ -195,11 +234,14 @@ Tools register at startup — only if the required API key exists. No key, no to
 | `HF_TOKEN` | `llm_complete` | HuggingFace Inference API |
 | `BRAVE_API_KEY` | `web_search` | Independent web index |
 | `TAVILY_API_KEY` | `web_search` | AI-optimized search with synthesized answers |
-| `DATABASE_URL` | `cloud DB` | e.g. Neon, Supabase |
-| `DATABASE_URL` | `db_query`, `persist_result` | SQLite read + PostgreSQL write |
-| *(always)* | `list_active_tools` | Shows key names only — never values |
+| `DATABASE_URL` | `persist_result`, `persist_status` | Long-term memory bridge (queue without it) |
+| `SHELLMASTER_TOKEN` | `shellmaster*` | ⛔ SECURITY LEVEL ROT — local only, `active="false"` |
+| *(always)* | `list_active_tools` | Shows key names only — never values. Plus `pricing_stats` |
 | *(always)* | `health_check` | Status + uptime + active transport |
-| *(always)* | `get_model_info` | Limits, costs, capabilities per model |
+| *(always)* | `get_model_info` | Limits, costs, capabilities per model (auto-merged) |
+| *(always)* | `get_model_pricing` | Auto-fetched costs — `.pyfun` values win as override |
+| *(always)* | `refresh_pricing` | Force refresh from OpenRouter + LiteLLM |
+| *(always)* | `db_query` | Read-only SELECT on internal hub state |
 
 For all key names see [`app/.pyfun`](app/.pyfun).
 
@@ -216,12 +258,15 @@ system_prompt    = "You are an expert code reviewer. Analyze the given code for
 [TOOL.code_review_END]
 ```
 
-Current built-in tools: `llm_complete`, `code_review`, `summarize`, `translate`, `web_search`, `db_query`  
-Future hooks (commented, ready): `image_gen`, `code_exec`, `shellmaster_2.0`, Discord, GitHub webhooks
+Current built-in tools: `llm_complete`, `code_review`, `summarize`, `translate`, `web_search`, `db_query`, `persist_result`, `persist_status`
+Future hooks (commented, ready): `image_gen`, `code_exec`, ShellMaster 2.0 (ROT — local only), Discord, GitHub webhooks
+
+</details>
 
 ---
 
-## LLM Fallback Chain
+<details>
+<summary><b>🔁 Fallback chain</b></summary>
 
 All LLM providers share one `llm_complete` tool. If a provider fails, the hub walks the fallback chain from `.pyfun`:
 
@@ -241,9 +286,13 @@ fallback_to = "openrouter"
 
 Same pattern applies to search providers (`brave → tavily`).
 
----
+</details>
+
+--- 
 
-## Quick Start
+
+<details open>
+<summary><b>🚀 Quick start</b></summary>
 
 ### HuggingFace Spaces (recommended)
 
@@ -271,16 +320,22 @@ Minimum required ENV vars (everything else is optional):
 PYFUNDAMENTS_DEBUG=""
 LOG_LEVEL="INFO"
 LOG_TO_TMP=""
-ENABLE_PUBLIC_LOGS="true"
+ENABLE_PUBLIC_LOGS="false"
 HF_TOKEN=""
 HUB_SPACE_URL=""
 ```
 
+> Note: HF Spaces prints stdout to a **publicly visible log tab**. `ENABLE_PUBLIC_LOGS="false"` keeps your logs yours. Default in code is still `true` — my fundament, my call, documented everywhere; flip it consciously.
+
 Transport is configured in `app/.pyfun [HUB]` — not via ENV.
 
+</details>
+
 ---
 
-## Connect an MCP Client
+
+<details>
+<summary><b>🔗 Connect an MCP client</b></summary>
 
 ### Streamable HTTP (default — MCP spec 2025-11-25)
 
@@ -321,16 +376,21 @@ Transport is configured in `app/.pyfun [HUB]` — not via ENV.
 }
 ```
 
-> Same URL (`/mcp`) for both transports — the protocol is negotiated automatically.  
+> Same URL (`/mcp`) for both transports — the protocol is negotiated automatically.
 > SSE fallback is for older clients that don't support Streamable HTTP yet.
+> (`HUB_STATELESS="true"` is intentional for HF Spaces — no `Mcp-Session-Id` header is expected, not a bug.)
+
+</details>
+
 
 ---
 
-## Desktop Client
-###### (experimental — ~80% AI generated)
 
-A full PySide6 desktop client is included in `DESKTOP_CLIENT/hub.py`.  
-Communicates via the REST `/api` endpoint — no MCP protocol overhead.  
+<details>
+<summary><b>🖥 Desktop client (experimental — ~80 % me, 20 % typing assistant)</b></summary>
+
+A full PySide6 desktop client is included in `DESKTOP_CLIENT/hub.py`.
+Communicates via the REST `/api` endpoint — no MCP protocol overhead.
 Ideal for private or non-public Spaces.
 
 ```bash
@@ -341,6 +401,7 @@ python DESKTOP_CLIENT/hub.py
 ```
 
 **Features:**
+
 - Multi-chat with persistent history
 - Tool / Provider / Model selector loaded live from your Hub
 - File attachments: images, PDF, CSV, Excel, ZIP, source code
@@ -351,9 +412,12 @@ python DESKTOP_CLIENT/hub.py
 
 [→ Desktop Client docs](DESKTOP_CLIENT/README.md)
 
+</details>
+
 ---
 
-## CMS & Custom Clients
+<details>
+<summary><b>🧩 CMS & custom clients</b></summary>
 
 | Client | Interface used | Notes |
 | :--- | :--- | :--- |
@@ -363,9 +427,14 @@ python DESKTOP_CLIENT/hub.py
 | Claude Desktop | MCP `/mcp` | Streamable HTTP |
 | Cursor / Windsurf | MCP `/mcp` | Streamable HTTP |
 
+</details>
+
+
 ---
 
-## Configuration (.pyfun)
+
+<details>
+<summary><b>⚙️ Configuration (.pyfun) — one file to rule the app</b></summary>
 
 `app/.pyfun` is the single source of truth for all app behavior. Three tiers:
 
@@ -385,6 +454,8 @@ HUB_PORT        = "7860"
 [HUB_END]
 ```
 
+**About `[MODELS]` costs (v1.2.0):** auto-pricing fills everything from OpenRouter + LiteLLM. Manual `cost_*` lines only remain for models no external source can know — my own deployments. If you ever get different conditions than the public lists (custom deals exist), just add `cost_*` lines for THAT model — `.pyfun` wins, always. The section also carries `requests_per_min/day`, `context_tokens`, `capabilities` and the provider mapping — none of that exists in any price API.
+
 Adding a new LLM provider — two steps:
 
 ```ini
@@ -407,9 +478,14 @@ _PROVIDER_CLASSES = {
 }
 ```
 
+</details>
+
+
 ---
 
-## Dependencies
+
+<details>
+<summary><b>📦 Dependencies</b></summary>
 
 ```
 # PyFundaments Core (always required)
@@ -432,12 +508,17 @@ requests         — sync HTTP for tool workers
 # psycopg2-binary  — alternative PostgreSQL driver
 ```
 
-> **Note:** The package is `mcp` (not `fastmcp`) — `FastMCP` is imported from `mcp.server.fastmcp`.  
+> **Note:** The package is `mcp` (not `fastmcp`) — `FastMCP` is imported from `mcp.server.fastmcp`.
 > Streamable HTTP support requires `mcp >= 1.6.0`.
 
+</details>
+
+
 ---
 
-## Security Design
+
+<details>
+<summary><b>🛡 Security design</b></summary>
 
 - API keys live in HF Secrets / `.env` — never in `.pyfun`, never in code
 - `list_active_tools` returns key **names** only — never values
@@ -446,16 +527,21 @@ requests         — sync HTTP for tool workers
 - Direct execution of `app/app.py` blocked by design — warning + null-fundaments fallback
 - `fundaments/` initialized conditionally — missing services degrade gracefully, never crash
 - Streamable HTTP uses standard Bearer headers — no token-in-URL (unlike SSE)
+- ShellMaster: **SECURITY LEVEL ROT** — hardblock list (rm -rf, mkfs, …), JSONL command registry, explicit confirmation before every execution, local-only (`localhost:5004`), token via `.env`
 
 > PyFundaments is not perfect. But it's more secure than most of what runs in production today.
 
 [→ Full Security Policy](SECURITY.md)
 
+</details>
+
+
 ---
 
-## Foundation
+<details>
+<summary><b>🧱 Foundation: PyFundaments</b></summary>
 
-Built on [PyFundaments](PyFundaments.md) — a security-first Python boilerplate:
+Built on [PyFundaments](PyFundaments.md) — a security-first Python boilerplate, crafted by hand over months (see the usernote at the top):
 
 - `config_handler.py` — env loading with validation
 - `postgresql.py` — async DB pool (Guardian-only)
@@ -463,41 +549,86 @@ Built on [PyFundaments](PyFundaments.md) — a security-first Python boilerplate
 - `access_control.py` — role/permission management
 - `user_handler.py` — user lifecycle management
 - `security.py` — unified security manager composing the above
+- `debug.py` — conditional startup diagnostics
 
 None accessible from `app/*`. Injected as a validated dict by `main.py`.
 
-[→ PyFundaments Function Overview](PyFundaments%20–%20Function%20Overview.md)  
-[→ Module Docs](docs/app/)  
+[→ PyFundaments Function Overview](PyFundaments%20–%20Function%20Overview.md)
+[→ Module Docs](docs/app/)
 [→ Source Repo](https://github.com/VolkanSah/Multi-LLM-API-Gateway)
 
+</details>
+
 ---
 
-## Related Projects
+<details><summary><b>🛤️ Roadmap</b></summary>
+
+## haha that's good!
+- [x] 10 months before...
+- [x] some blackouts
+- [x] more blackouts
+- [x] ... month 6 WTF... runs but only stupid secure LLM wrapper and tools...
+- [x] ... pff brick again!
+- [x] ... fuck!
+- [x] ... rewrite
+- [x] fuck Neon DB + MCP changes secure stuff! fuck
+- [x] rewritten
+- [x] GLM checked it, stupid guy! but finds 2 hidden design bugs, no execution but stupid fail!
+- [x] Claude checks again and again and again, my 5 hours limit used in 1.23 min. A record of my self, normally need 2 minutes
+- [x] wtf, fuck you Claude, fuck you Gemini, fuck you GLM, fuck you Kimi, fuck you DeepSeek, all others I do not use
+- [x] fuck! but runs again! I see my first instinct was the best, AI made me crazy!
+- [x] new rewrite with Claude Sonnet, first kick this asshole in his fucking balls 12 times! I get poor bitch!
+- [x] it runs...
+- [x] Fuck yeah, stable fast, secure and against scammers! only for privates!
+- [x] fail architecture for vibecoders!
+- [x] README AI slop from AI with a fucking touch of me!
+- [x] conditional initialization of fundament modules...
+- [x] Fundament modules are ready for the app logic.
+- [x] PostgreSQL bridge activ
+- [x] ShellMaster & Discord API not 100 % finished!
+- [X] tools an´d stiff.. later to much yet!
+- [ ] some futers.. still crafting
+     
+</details>
+
+
 
-- [Customs LLMs for free — Build Your Own LLM Service](https://github.com/VolkanSah/SmolLM2-customs/)
-- [WP AI Hub (WordPress Client)](https://github.com/VolkanSah/WP-AI-HUB/)
-- [ShellMaster (2023 precursor)](https://github.com/VolkanSah/ChatGPT-ShellMaster)
 
 ---
 
-## History
 
-[ShellMaster](https://github.com/VolkanSah/ChatGPT-ShellMaster) (2023, MIT) was the precursor — browser-accessible shell for ChatGPT with session memory, built before MCP was a concept. Universal MCP Hub is its natural evolution: same idea, proper architecture, dual interface.
+<details>
+<summary><b>📜 History & related projects</b></summary>
+
+[ShellMaster](https://github.com/VolkanSah/ChatGPT-ShellMaster) (2023, MIT) was the precursor — browser-accessible shell for ChatGPT with session memory, built before MCP was a concept. Universal AI Hub is its natural evolution: same idea, proper architecture, dual interface. And yes — the ShellMaster idea is back as a tool hook, now with a red security level and a conscience.
+
+Related:
+
+- [Customs LLMs for free — Build Your Own LLM Service](https://github.com/VolkanSah/SmolLM2-customs/)
+- [WP AI Hub (WordPress Client)](https://github.com/VolkanSah/WP-AI-HUB/)
+- [ShellMaster (2023 precursor)](https://github.com/VolkanSah/ChatGPT-ShellMaster)
+
+</details>
 
 ---
 
-## License
 
-Dual-licensed:
+<details>
+<summary><b>⚖️ License — Multi-License & ESOL (mandatory)</b></summary>
 
-- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)
-- [Ethical Security Operations License v1.1 (ESOL)](ESOL) — mandatory, non-severable
+- Projekt GNU Affero General Public License v3.0 [see License](https://www.gnu.org/licenses/agpl-3.0.html) + Ethical Security Operations License v2.1 [see License](ESOL) — mandatory, non-severable
+- Some scripts i made Apache License 2.0 [see License](https://www.apache.org/licenses/LICENSE-2.0) + GNU General Public License v3.0 [see License](https://www.gnu.org/licenses/gpl-3.0.html) + MIT License [see License](https://opensource.org/licenses/MIT) (only for as for examples, some skills and agents public on MIT or other open source license i use here in this hub for showcases, see files for more infos)
 
-By using this software you agree to all ethical constraints defined in ESOL v1.1.
+##### By using this software you agree to all ethical constraints defined in ESOL v2.1.
+
+</details>
 
 ---
 
-*Architecture, security decisions, and PyFundaments by Volkan Kücükbudak.*  
-*Built with Claude (Anthropic) as a typing assistant for docs (and the occasional bug).*
+*Architecture, security decisions and 100 % of brocken code ( ok 100 % Running with less than 1 % mistakes) and PyFundaments by me.*
+*Built with Claude (Anthropic not claude coder or codex or wtf!) after 20 % own desaster 5 seps bevor relase, played with GLM to see an outher focus but at the end as a typing assistant for docs (and the occasional bug) after i brick my hole work after i made it to complex... so i mean its not ready!*
+
+> crafted with passion - just wanted to understand how it works, don't actually need it, have a CLI 😄
+> 
+> README.md craftet (rewritten) by gemini 3 Pro , fixed by me, looks terrible i know! AI slop from claude, geminie and me! Soon better i sewar! 
 
-> crafted with passion — just wanted to understand how it works, don't actually need it, have a CLI 😄

SECURITY.md

@@ -0,0 +1,146 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you find a security issue, please do **not** open a public GitHub issue.
+
+Report privately via: [GitHub Security Advisories](https://github.com/VolkanSah/Universal-MCP-Hub/security/advisories/new)
+
+Include: what you found, how to reproduce it, and what impact you think it has. You'll get a response within 72 hours. If the issue is confirmed, a fix will be prioritized before any public disclosure.
+
+---
+
+## Security Architecture
+
+### The Guardian Pattern
+
+`main.py` is the only process that ever touches secrets. It reads `.env` / HF Space Secrets, initializes `fundaments/*` conditionally, and passes the results into `app/*` as a validated dict. After that handoff, `app/*` has no path back to the raw environment.
+
+```
+.env / HF Secrets
+      │
+      ▼
+main.py (Guardian) — only entry point
+      │
+      │  initializes fundaments/* conditionally
+      │  injects as: fundaments = {"config": ..., "db": ..., "encryption": ..., ...}
+      │
+      ▼
+app/app.py — unpacks fundaments ONCE at startup, never stores globally
+      │
+      └── app/* modules — read only from app/.pyfun, never from os.environ
+```
+
+This is enforced structurally. `app/*` has no import of `fundaments/`, no `os.environ` calls, no `.env` access. It's not a coding convention — it's an import boundary.
+
+---
+
+### Secret Handling
+
+- API keys live exclusively in HF Space Secrets or `.env` — never in `app/.pyfun`, never in source code
+- `app/.pyfun` references only ENV variable **names** (e.g. `env_key = "ANTHROPIC_API_KEY"`) — never values
+- `list_active_tools` returns key names only — the actual key values are never exposed through any MCP tool
+- `fundaments/` modules are initialized only if their required ENV vars are present — missing config = service skipped, not crashed
+
+---
+
+### Encryption (`fundaments/encryption.py`)
+
+When `MASTER_ENCRYPTION_KEY` and `PERSISTENT_ENCRYPTION_SALT` are set:
+
+- Key derivation: **PBKDF2-HMAC-SHA256**, 480,000 iterations, 256-bit output
+- Encryption: **AES-256-GCM** — authenticated encryption, provides both confidentiality and integrity
+- Each encryption operation uses a fresh random 96-bit nonce
+- Authentication tag (128-bit) is stored alongside ciphertext — decryption fails loudly if data was tampered
+- File encryption uses streaming with 8 KB chunks — nonce prepended, tag appended to file
+- If encryption keys are not set, the service is skipped cleanly — the app runs without it
+
+---
+
+### Authentication (`fundaments/user_handler.py`)
+
+- Passwords hashed with **PBKDF2-SHA256** via `passlib`
+- Sessions stored in SQLite with IP address + User-Agent binding — `validate_session()` checks both
+- Session IDs are regenerated on login (session fixation prevention)
+- Failed login attempts tracked per user — account locks after 5 consecutive failures
+- Session table uses `ON DELETE CASCADE` — deleting a user removes all their sessions automatically
+
+---
+
+### Access Control (`fundaments/access_control.py`)
+
+- Role-based permission system backed by PostgreSQL (cloud DB, Guardian-only)
+- Schema: `users → user_role_assignments → user_roles → role_permissions → user_permissions`
+- All queries use parameterized statements via `asyncpg` — no string interpolation
+- `has_permission()` checks the full role→permission chain per request
+- `AccessControl` only initializes if a DB connection is available — degrades gracefully otherwise
+
+---
+
+### Database Security (`fundaments/postgresql.py`)
+
+**Cloud DB (asyncpg pool):**
+- SSL enforced at minimum `sslmode=require` — upgraded automatically if not set
+- Neon.tech quirks handled: `statement_timeout` stripped from DSN (unsupported, causes silent failures), keepalives set
+- Credentials masked in all log output — full DSN only in `DEBUG` level logs
+- SSL runtime check via `pg_stat_ssl` on every new connection (cloud providers: warning only if unavailable)
+- Automatic pool restart on Neon connection termination (sqlstate `08006`)
+- Pool: min 1 / max 10 connections, connect timeout 5s, command timeout 30s
+
+**Internal SQLite (`app/db_sync.py` + `fundaments/user_handler.py`):**
+- Same SQLite file, separate tables — zero overlap enforced by code
+- `users` + `sessions` → owned by `user_handler.py` (Guardian layer)
+- `hub_state` + `tool_cache` → owned by `db_sync.py` (app/* layer)
+- `db_query` MCP tool exposes SELECT-only access to `hub_state` and `tool_cache` — cannot reach `users` or `sessions`
+- SELECT enforcement: non-SELECT queries raise `ValueError` before execution
+- On HuggingFace Spaces: SQLite auto-relocated to `/tmp/` (HF filesystem is read-only outside `/tmp/`)
+
+---
+
+### MCP Transport Security
+
+- All MCP traffic routes through Quart `/mcp` endpoint before reaching FastMCP
+- This is the natural interception point for auth checks, rate limiting, and payload logging — none are optional add-ons
+- `/crypto` endpoint exists but returns `501` until the app-layer encryption wrapper is implemented — not bypassed, not silently ignored
+- `health_check` and `list_active_tools` are always available — they expose no secrets, only status and key names
+
+---
+
+### Sandboxing Rules
+
+These rules are enforced by code structure, not just documentation:
+
+| Rule | Enforced by |
+| :--- | :--- |
+| `app/*` never reads `os.environ` | No `os.environ` calls in any `app/` file |
+| `app/*` never imports `fundaments/` | No cross-imports between layers |
+| `fundaments/` services injected, not constructed in `app/*` | `start_application(fundaments)` signature |
+| Direct execution of `app/app.py` blocked | `__main__` guard with null-fundaments warning |
+| `db_query` tool is SELECT-only | `ValueError` raised before any non-SELECT execution |
+| API keys never in `.pyfun` | `.pyfun` parser only reads key names, never resolves them |
+
+---
+
+### What This Project Does Not Claim
+
+- It is not a penetration-tested security product
+- The encrypted `/crypto` endpoint is not yet implemented
+- Search provider implementations (Brave, Tavily) are pending — the tool registers as placeholder
+- This is a personal/community project — use in production at your own assessment
+
+> PyFundaments is not perfect. But it's more secure than most of what runs in production today.
+
+---
+
+## Supported Versions
+
+| Version | Supported |
+| :--- | :--- |
+| latest (`main`) | ✅ |
+| older forks | ❌ — fork at your own risk |
+
+---
+
+## License Note
+
+This project is dual-licensed under Apache 2.0 and the [Ethical Security Operations License v1.1 (ESOL)](ESOL). Using this software for surveillance, unauthorized access, or harm to others automatically terminates your license.

app/.pyfun

@@ -18,15 +18,12 @@
 # DO NOT DELETE — file identifier used by all parsers
 [PYFUN_FILE = .pyfun]
 
-# =============================================================================
-# HUB — Core identity & transport config
-# =============================================================================
 # =============================================================================
 # HUB — Core identity & transport config
 # =============================================================================
 [HUB]
 HUB_NAME            = "Multi-LLM-API-Gateway"
-HUB_VERSION         = "1.0.1"
+HUB_VERSION         = "1.2.0"
 HUB_DESCRIPTION     = "Universal Hub built on PyFundaments"
 
 # Transport: sse (legacy/HF Spaces fallback) | streamable-http (MCP spec 2025-11-25)
@@ -40,17 +37,24 @@ HUB_HOST            = "0.0.0.0"
 HUB_PORT            = "7860"
 HUB_MODE            = "mcp"
 HUB_SPACE_URL       = ""
+
+# Optional Token-Schutz für /api, /crypto und /mcp (siehe app/auth.py).
+# Hier steht nur der NAME der ENV-Variable — der Token selbst kommt in .env / Space-Secret.
+# Variable nicht gesetzt = Schutz AUS (Hub verhält sich wie bisher).
+# Client sendet:  X-Hub-Token: <token>   oder   Authorization: Bearer <token>
+HUB_AUTH_ENV        = "HUB_API_TOKEN"
 [HUB_END]
 
 # =============================================================================
 # HUB_LIMITS — Request & retry behavior
 # =============================================================================
 [HUB_LIMITS]
-MAX_PARALLEL_REQUESTS   = "5"
-RETRY_COUNT             = "3"
-RETRY_DELAY_SEC         = "2"
+MAX_PARALLEL_REQUESTS   = "5"     # gleichzeitige Provider-Calls (Semaphore)
+RETRY_COUNT             = "3"     # Versuche pro Provider (inkl. erstem) bei 429/5xx/Verbindungsfehler
+RETRY_DELAY_SEC         = "2"     # Pause zwischen den Versuchen; Timeouts werden NICHT wiederholt
 REQUEST_TIMEOUT_SEC     = "60"
 SEARCH_TIMEOUT_SEC      = "30"
+MAX_TOKENS_CAP          = "8192"  # harte Obergrenze für max_tokens pro Call (0 = aus)
 [HUB_LIMITS_END]
 
 # =============================================================================
@@ -62,14 +66,26 @@ SEARCH_TIMEOUT_SEC      = "30"
 # ── LLM Providers ─────────────────────────────────────────────────────────────
 [LLM_PROVIDERS]
 
+  # ───────────────────────────────────────────────────────────────────────────
+  # type = welcher Handler den Provider spricht:
+  #   "openai_compat" → generisch (/chat/completions) — KEIN Code nötig, nur dieser Block
+  #   "anthropic" | "gemini" → eigene Klassen in providers.py
+  # Nur für openai_compat (alles optional):
+  #   auth_header = "Authorization" (Default) | auth_scheme = "Bearer" (Default, "" = Key pur)
+  #   chat_path   = "/chat/completions" (Default)
+  #   header.<Name> = "..."   Extra-Header. Platzhalter: {key} = API-Key,
+  #                           {env:NAME|fallback} = Wert aus ENV (mit Fallback)
+  # Modelle gehören NICHT hierher, sondern nach [MODELS] (Name = echte API-ID).
+  # ───────────────────────────────────────────────────────────────────────────
 
   #  customs LLM
   [LLM_PROVIDER.smollm]
   active        = "true"
+  type          = "openai_compat"
   base_url      = "https://codey-lab-smollm2-customs.hf.space/v1"
   env_key       = "SMOLLM_API_KEY"
+  header.X-IP-Token = "{key}"
   default_model = "smollm2-360m"
-  models        = "smollm2-360m, codey-lab/model.universal-mcp-hub"
   fallback_to   = "gemini"
   [LLM_PROVIDER.smollm_END]
 
@@ -77,63 +93,75 @@ SEARCH_TIMEOUT_SEC      = "30"
 
   [LLM_PROVIDER.anthropic]
   active              = "true"
+  type                = "anthropic"
   base_url            = "https://api.anthropic.com/v1"
   env_key             = "ANTHROPIC_API_KEY"
   api_version_header  = "2023-06-01"
-  default_model       = "claude-haiku-4-5-20251001"
-  models              = "claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001"
-  supports_cache   = "true"
+  default_model       = "claude-haiku-5-5"
+  supports_cache      = "true"
   fallback_to         = "gemini"
   [LLM_PROVIDER.anthropic_END]
 
   [LLM_PROVIDER.gemini]
   active        = "true"
+  type          = "gemini"
   base_url      = "https://generativelanguage.googleapis.com/v1beta"
   env_key       = "GEMINI_API_KEY"
   default_model = "gemini-2.5-flash"
-  models        = "gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-3.1-flash-lite-preview, gemini-3-flash-preview, gemini-3.1-pro-preview"
   supports_cache = "true"
   fallback_to   = "openrouter"
   [LLM_PROVIDER.gemini_END]
 
   [LLM_PROVIDER.openrouter]
   active              = "true"
+  type                = "openai_compat"
   base_url            = "https://openrouter.ai/api/v1"
   env_key             = "OPENROUTER_API_KEY"      # → .env: OPENROUTER_API_KEY=sk-or-...
+  header.HTTP-Referer = "{env:APP_URL|https://huggingface.co}"
+  header.X-Title      = "{env:HUB_NAME|Universal MCP Hub}"
   default_model       = "nvidia/nemotron-nano-9b-v2:free"
-  models              = "meta-llama/llama-3-8b-instruct, mistralai/mistral-7b-instruct, nvidia/nemotron-nano-9b-v2:free, google/gemma-3-27b-it:free, openai/gpt-oss-20b:free, mistralai/Mistral-7B-Instruct-v0.3, meta-llama/Llama-3.3-70B-Instruct"
-  fallback_to         = "huggingface"                      
+  fallback_to         = "huggingface"
   [LLM_PROVIDER.openrouter_END]
 
   [LLM_PROVIDER.huggingface]
   active             = "true"
+  type               = "openai_compat"
+  # TODO prüfen: HF hat (soweit ich weiß) auf https://router.huggingface.co/v1 umgestellt
   base_url           = "https://api-inference.huggingface.co/v1"
   env_key            = "HF_TOKEN"                # → .env: HF_TOKEN=hf_...
-  default_model = "Qwen/Qwen2.5-Coder-32B-Instruct"
-  models        = "Qwen/Qwen2.5-Coder-32B-Instruct, meta-llama/Llama-3.1-8B-Instruct, mistralai/Mistral-Nemo-Instruct-2407, Qwen/Qwen2.5-72B-Instruct"
-  
+  default_model      = "Qwen/Qwen2.5-Coder-32B-Instruct"
   fallback_to        = "smollm" # ← last in chain, no further fallback
   [LLM_PROVIDER.huggingface_END]
 
-  # ── Add more LLM providers below ──────────────────────────────────────────
+  # ── Neuer OpenAI-kompatibler Provider = NUR so ein Block + Key in .env ─────
+  # (Beispiele zum Einkommentieren — kein Python nötig. Passende Modelle in [MODELS] eintragen!)
   # [LLM_PROVIDER.mistral]
-  # active            = "false"
+  # active            = "true"
+  # type              = "openai_compat"
   # base_url          = "https://api.mistral.ai/v1"
   # env_key           = "MISTRAL_API_KEY"
-  # default_model     = "mistral-large-latest"
-  # models            = "mistral-large-latest, mistral-small-latest"
+  # default_model     = "mistral-small-latest"
   # fallback_to       = ""
   # [LLM_PROVIDER.mistral_END]
 
   # [LLM_PROVIDER.openai]
-  # active            = "false"
+  # active            = "true"
+  # type              = "openai_compat"
   # base_url          = "https://api.openai.com/v1"
   # env_key           = "OPENAI_API_KEY"
-  # default_model     = "gpt-4o"
-  # models            = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
+  # default_model     = "gpt-4o-mini"
   # fallback_to       = ""
   # [LLM_PROVIDER.openai_END]
 
+  # [LLM_PROVIDER.xai]
+  # active            = "true"
+  # type              = "openai_compat"
+  # base_url          = "https://api.x.ai/v1"
+  # env_key           = "XAI_API_KEY"
+  # default_model     = "grok-4"
+  # fallback_to       = ""
+  # [LLM_PROVIDER.xai_END]
+
 [LLM_PROVIDERS_END]
 
 # ── Search Providers ───────────────────────────────────────────────────────────
@@ -158,6 +186,20 @@ SEARCH_TIMEOUT_SEC      = "30"
   fallback_to         = ""
   [SEARCH_PROVIDER.tavily_END]
 
+  # Keyless Notfall-Fallback (liest die öffentliche HTML-Seite — es gibt KEINE offizielle DDG-API,
+  # daher fragil + bewusst "sanft": globaler Cooldown, kein Retry, ehrlicher User-Agent).
+  # Aktivieren: active = "true" UND bei tavily  fallback_to = "duckduckgo"
+  # (ungetestet gegen das echte DuckDuckGo — erst ausprobieren!)
+  [SEARCH_PROVIDER.duckduckgo]
+  active              = "false"
+  requires_key        = "false"                   # kein API-Key nötig
+  base_url            = "https://html.duckduckgo.com/html/"
+  min_interval_sec    = "300"                     # mind. 5 Min zwischen zwei Anfragen
+  default_results     = "5"
+  max_results         = "10"
+  fallback_to         = ""
+  [SEARCH_PROVIDER.duckduckgo_END]
+
   # ── Add more search providers below ───────────────────────────────────────
   # [SEARCH_PROVIDER.serper]
   # active            = "false"
@@ -190,199 +232,132 @@ SEARCH_TIMEOUT_SEC      = "30"
 # =============================================================================
 # MODELS — Token & rate limits per model
 # Parser builds: MODELS[provider][model_name] → limits dict
+# COSTS: cost_*-Zeilen sind seit v1.1 OPTIONAL — [PRICING] füllt sie automatisch
+# aus OpenRouter + LiteLLM nach (OR markiert nie auf: per-Token = Vendor-
+# Listenpreis; ~5.5% Gebühr fällt nur beim Kredit-Kauf an, nicht pro Token).
+# Deine manuellen cost_* gewinnen IMMER als Override — sinnvoll für eigene
+# Deployments (smollm = 0.0, weil eigener Server) und Sonderkonditionen.
 # =============================================================================
 [MODELS]
 
+  # ───────────────────────────────────────────────��───────────────────────────
+  # REGELN (damit nichts mehr veraltet):
+  #  - Block-Name = ECHTE API-ID so wie der Provider sie erwartet
+  #    (OpenRouter: "vendor/name[:free]", HF: "Org/Name", Anthropic/Gemini: wie in der API)
+  #  - provider = Pflicht. Hat ein Tool nur ein model (ohne provider), nimmt der Hub
+  #    den Provider von hier.
+  #  - context_tokens / max_output_tokens / cost_* NICHT pflegen — [PRICING] holt sie
+  #    live aus OpenRouter + LiteLLM. Manuelle Werte gewinnen IMMER; nutze sie nur für
+  #    das, was nur du weißt (eigener Server, Sonderkonditionen). max_output_tokens
+  #    begrenzt zusätzlich die Antwortlänge (Clamp).
+  #  - requests_per_min/day = dein Account-Limit, wird nur angezeigt, NICHT erzwungen.
+  #  - OpenRouter-Modelle, die es im Live-Katalog nicht mehr gibt, meldet der Hub
+  #    beim Pricing-Refresh als "stale_models" (Log + list_active_tools + refresh_pricing).
+  # ───────────────────────────────────────────────────────────────────────────
+
   [MODEL.claude-opus-4-6]
   provider            = "anthropic"
-  context_tokens      = "200000"
-  max_output_tokens   = "32000"
   requests_per_min    = "5"
   requests_per_day    = "300"
-  cost_input_per_1k   = "0.015"                  # USD — update as pricing changes
-  cost_output_per_1k  = "0.075"
   capabilities        = "text, code, analysis, vision"
   [MODEL.claude-opus-4-6_END]
 
   [MODEL.claude-sonnet-4-6]
   provider            = "anthropic"
-  context_tokens      = "200000"
-  max_output_tokens   = "16000"
   requests_per_min    = "50"
   requests_per_day    = "1000"
-  cost_input_per_1k   = "0.003"
-  cost_output_per_1k  = "0.015"
   capabilities        = "text, code, analysis, vision"
   [MODEL.claude-sonnet-4-6_END]
 
   [MODEL.claude-haiku-4-5-20251001]
   provider            = "anthropic"
-  context_tokens      = "200000"
-  max_output_tokens   = "8000"
   requests_per_min    = "50"
   requests_per_day    = "2000"
-  cost_input_per_1k   = "0.00025"
-  cost_output_per_1k  = "0.00125"
   capabilities        = "text, code, fast"
   [MODEL.claude-haiku-4-5-20251001_END]
 
   [MODEL.gemini-3.1-flash-lite-preview]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "8192"
   requests_per_min    = "15"
   requests_per_day    = "1000"
-  cost_input_per_1k   = "0.00010"
-  cost_output_per_1k  = "0.00040"
   capabilities        = "text, code, vision, fast, cheap"
   [MODEL.gemini-3.1-flash-lite-preview_END]
 
   [MODEL.gemini-3-flash-preview]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "8192"
   requests_per_min    = "10"
   requests_per_day    = "1000"
-  cost_input_per_1k   = "0.00050"
-  cost_output_per_1k  = "0.00300"
   capabilities        = "text, code, vision, audio, frontier"
   [MODEL.gemini-3-flash-preview_END]
 
   [MODEL.gemini-3.1-pro-preview]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "64000"
   requests_per_min    = "5"
   requests_per_day    = "1000"
-  cost_input_per_1k   = "0.00200"
-  cost_output_per_1k  = "0.01200"
   capabilities        = "text, code, vision, audio, reasoning, agents"
   [MODEL.gemini-3.1-pro-preview_END]
 
   [MODEL.gemini-2.5-flash]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "8192"
   requests_per_min    = "15"
   requests_per_day    = "1500"
-  cost_input_per_1k   = "0.00010"
-  cost_output_per_1k  = "0.00040"
   capabilities        = "text, code, vision, audio"
   [MODEL.gemini-2.5-flash_END]
 
   [MODEL.gemini-2.5-flash-lite]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "8192"
   requests_per_min    = "15"
   requests_per_day    = "1500"
-  cost_input_per_1k   = "0.00010"
-  cost_output_per_1k  = "0.00040"
   capabilities        = "text, code, vision, audio"
-  [MODEL.gemini-2.0-flash-lite_END]
-
+  [MODEL.gemini-2.5-flash-lite_END]
 
   [MODEL.gemini-2.0-flash]
   provider            = "gemini"
-  context_tokens      = "1000000"
-  max_output_tokens   = "8192"
   requests_per_min    = "15"
   requests_per_day    = "1500"
-  cost_input_per_1k   = "0.00010"
-  cost_output_per_1k  = "0.00040"
   capabilities        = "text, code, vision, audio"
   [MODEL.gemini-2.0-flash_END]
 
-  
-  [MODEL.mistral-7b-instruct]
+  [MODEL.mistralai/mistral-7b-instruct]
   provider            = "openrouter"
-  context_tokens      = "32000"
-  max_output_tokens   = "4096"
-  requests_per_min    = "60"
-  requests_per_day    = "10000"
-  cost_input_per_1k   = "0.00006"
-  cost_output_per_1k  = "0.00006"
   capabilities        = "text, code, fast, cheap"
-  [MODEL.mistral-7b-instruct_END]
-  
-  [MODEL.dolphin-mistral-24b-venice-edition]
+  [MODEL.mistralai/mistral-7b-instruct_END]
+
+  [MODEL.cognitivecomputations/dolphin-mistral-24b-venice-edition:free]
   provider            = "openrouter"
-  context_tokens      = "32768"
-  max_output_tokens   = "4096"
-  requests_per_min    = ""
-  requests_per_day    = ""
-  cost_input_per_1k   = "0.00000"
-  cost_output_per_1k  = "0.00000"
   capabilities        = "uncensored, text, code, fast, very cheap"
-  [MODEL.dolphin-mistral-24b-venice-edition_END]
+  [MODEL.cognitivecomputations/dolphin-mistral-24b-venice-edition:free_END]
 
-  [MODEL.nvidia-nemotron-nano-9b-v2]
+  [MODEL.nvidia/nemotron-nano-9b-v2:free]
   provider            = "openrouter"
-  context_tokens      = "131072"
-  max_output_tokens   = "4096"
-  requests_per_min    = ""
-  requests_per_day    = ""
-  cost_input_per_1k   = "0.00000"
-  cost_output_per_1k  = "0.00000"
   capabilities        = "text, code, reasoning, fast, free"
-  [MODEL.nvidia-nemotron-nano-9b-v2_END]
+  [MODEL.nvidia/nemotron-nano-9b-v2:free_END]
 
-  [MODEL.gemma-3-27b-it]
+  [MODEL.google/gemma-3-27b-it:free]
   provider            = "openrouter"
-  context_tokens      = "131072"
-  max_output_tokens   = "8192"
-  requests_per_min    = ""
-  requests_per_day    = ""
-  cost_input_per_1k   = "0.00000"
-  cost_output_per_1k  = "0.00000"
   capabilities        = "text, code, vision, multilingual, free"
-  [MODEL.gemma-3-27b-it_END]
+  [MODEL.google/gemma-3-27b-it:free_END]
 
-  [MODEL.gpt-oss-20b]
+  [MODEL.openai/gpt-oss-20b:free]
   provider            = "openrouter"
-  context_tokens      = "128000"
-  max_output_tokens   = "4096"
-  requests_per_min    = ""
-  requests_per_day    = ""
-  cost_input_per_1k   = "0.00000"
-  cost_output_per_1k  = "0.00000"
   capabilities        = "text, code, free"
-  [MODEL.gpt-oss-20b_END]
+  [MODEL.openai/gpt-oss-20b:free_END]
 
-  [MODEL.deephermes-3-llama-3-8b-preview]
+  [MODEL.nousresearch/deephermes-3-llama-3-8b-preview:free]
   provider            = "openrouter"
-  context_tokens      = "131072"
-  max_output_tokens   = "4096"
-  requests_per_min    = ""
-  requests_per_day    = ""
-  cost_input_per_1k   = "0.00000"
-  cost_output_per_1k  = "0.00000"
   capabilities        = "text, code, reasoning, uncensored, free"
-  [MODEL.deephermes-3-llama-3-8b-preview_END]
+  [MODEL.nousresearch/deephermes-3-llama-3-8b-preview:free_END]
 
-  [MODEL.Mistral-7B-Instruct-v0.3]
-  provider            = "openrouter"
-  context_tokens      = "32768"
-  max_output_tokens   = "4096"
-  requests_per_min    = "60"
-  requests_per_day    = "10000"
-  cost_input_per_1k   = "0.00006"
-  cost_output_per_1k  = "0.00006"
+  [MODEL.mistralai/Mistral-7B-Instruct-v0.3]
+  provider            = "huggingface"
   capabilities        = "text, code, fast, cheap"
-  [MODEL.Mistral-7B-Instruct-v0.3_END]
+  [MODEL.mistralai/Mistral-7B-Instruct-v0.3_END]
 
-  [MODEL.Llama-3.3-70B-Instruct]
-  provider            = "openrouter"
-  context_tokens      = "131072"
-  max_output_tokens   = "8192"
-  requests_per_min    = "60"
-  requests_per_day    = "10000"
-  cost_input_per_1k   = "0.00012"
-  cost_output_per_1k  = "0.00030"
+  [MODEL.meta-llama/Llama-3.3-70B-Instruct]
+  provider            = "huggingface"
   capabilities        = "text, code, reasoning, multilingual"
-  [MODEL.Llama-3.3-70B-Instruct_END]
+  [MODEL.meta-llama/Llama-3.3-70B-Instruct_END]
 
-  # customs llms
   [MODEL.smollm2-360m]
   provider           = "smollm"
   context_tokens     = "8192"
@@ -405,6 +380,46 @@ SEARCH_TIMEOUT_SEC      = "30"
   capabilities       = "text, assistant, navigation, free, custom, finetuned"
   [MODEL.codey-lab/model.universal-mcp-hub_END]
 
+  [MODEL.claude-opus-5-5]
+  provider            = "anthropic"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-opus-5-5_END]
+
+  [MODEL.claude-sonnet-5-5]
+  provider            = "anthropic"
+  capabilities        = "text, code, analysis, vision"
+  [MODEL.claude-sonnet-5-5_END]
+
+  [MODEL.claude-haiku-5-5]
+  provider            = "anthropic"
+  capabilities        = "text, code, fast"
+  [MODEL.claude-haiku-5-5_END]
+
+  [MODEL.meta-llama/llama-3-8b-instruct]
+  provider            = "openrouter"
+  capabilities        = "text, code, fast"
+  [MODEL.meta-llama/llama-3-8b-instruct_END]
+
+  [MODEL.Qwen/Qwen2.5-Coder-32B-Instruct]
+  provider            = "huggingface"
+  capabilities        = "text, code"
+  [MODEL.Qwen/Qwen2.5-Coder-32B-Instruct_END]
+
+  [MODEL.meta-llama/Llama-3.1-8B-Instruct]
+  provider            = "huggingface"
+  capabilities        = "text, code, fast"
+  [MODEL.meta-llama/Llama-3.1-8B-Instruct_END]
+
+  [MODEL.mistralai/Mistral-Nemo-Instruct-2407]
+  provider            = "huggingface"
+  capabilities        = "text, code, multilingual"
+  [MODEL.mistralai/Mistral-Nemo-Instruct-2407_END]
+
+  [MODEL.Qwen/Qwen2.5-72B-Instruct]
+  provider            = "huggingface"
+  capabilities        = "text, code, reasoning, multilingual"
+  [MODEL.Qwen/Qwen2.5-72B-Instruct_END]
+
 [MODELS_END]
 
 # =============================================================================
@@ -413,6 +428,10 @@ SEARCH_TIMEOUT_SEC      = "30"
 # =============================================================================
 [TOOLS]
 
+  # Optional pro Tool (llm + search): Antwort-Cache über db_sync.
+  #   cache = "true"  und  cache_ttl_sec = "3600"
+  # Default AUS (LLM-Antworten sind nicht deterministisch).
+
   [TOOL.llm_complete]
   active              = "true"
   description         = "Send prompt to any configured LLM provider"
@@ -467,11 +486,14 @@ SEARCH_TIMEOUT_SEC      = "30"
 
   [TOOL.persist_result]
   active           = "true"
-  description      = "Persist hub_state data to PostgreSQL for long-term storage"
+  description      = "Persist important results to long-term memory (PostgreSQL) — restart-safe queue in SQLite, flushes automatically"
   provider_type    = "persist"
   state_read_key   = ""          # welcher hub_state Key → leer = prompt direkt
   target_table     = "hub_results"
   timeout_sec      = "10"
+  # score-Parameter (optional, float) = reservierter Slot fuer den
+  # Bullshit-Filter — wird unverarbeitet durchgereicht und landet als
+  # eigene Spalte in PostgreSQL. Filter/Scoring baust DU, nicht der Hub.
   [TOOL.persist_result_END]
 
   # ── Future tools ──────────────────────────────────────────────────────────
@@ -491,10 +513,15 @@ SEARCH_TIMEOUT_SEC      = "30"
   # [TOOL.code_exec_END]
 
   # ── Shellmaster 2.0 ──────────────────────────────────────────────────────────
+  # SECURITY LEVEL: ROT — dein CLI-Commander. LLM generiert → Hardblock+
+  # Registry-Check → DEINE Bestätigung → Ausführung auf DEINEM lokalen
+  # Rechner (Agent :5004). NUR lokal — NIEMALS auf öffentlichen HF Spaces
+  # aktivieren! Token gehört in .env (shellmaster_env_key), nicht hierher.
   [TOOL.shellmaster]
   active                       = "false"
   shellmaster_agent_url        = "http://localhost:5004"
-  shellmaster_token            = ""
+  shellmaster_env_key          = "SHELLMASTER_TOKEN"   # → .env, wie bei allen Providern
+  shellmaster_token            = ""                    # Fallback nur für lokale Tests
   description                  = "AI-powered shell assistant — generates and executes safe shell commands"
   provider_type                = "llm"
   default_provider             = "smollm"
@@ -520,6 +547,43 @@ SEARCH_TIMEOUT_SEC      = "30"
   description = "List allowed ShellMaster commands from registry"
   [TOOL.shellmaster_commands_END]
 
+  # ── Integrationen (alle inaktiv, bis [DISCORD] / [GSC] unten aktiv sind) ──────
+  [TOOL.discord_post]
+  active              = "false"
+  description         = "Post a message to Discord (default channel / webhook)"
+  provider_type       = "discord"
+  [TOOL.discord_post_END]
+
+  [TOOL.gsc_query]
+  active              = "false"
+  description         = "Google Search Console: top queries/pages of a property (read-only)"
+  provider_type       = "gsc"
+  [TOOL.gsc_query_END]
+
+  # ── Skill-Datenbanken (app/db/skills/, gebaut mit local_tools/vector_hub) — nur lesen ───────
+  [TOOL.show_skills]
+  active              = "true"
+  description         = "List available skills (name, description, tags) — user + agent skills"
+  provider_type       = "skills"
+  skills_action       = "catalog"
+  [TOOL.show_skills_END]
+
+  [TOOL.search_skills]
+  active              = "true"
+  description         = "Search skills by keywords (BM25) — returns the best matching chunks"
+  provider_type       = "skills"
+  skills_action       = "search"
+  [TOOL.search_skills_END]
+
+  # LLM-Tools: Skills automatisch in den System-Prompt (überschreibt die globalen [SKILLS]-Schalter):
+  #   use_core   = "true"   core.db (Regeln/Restriktionen) voranstellen — kostet bei JEDEM Call Tokens
+  #   use_skills = "true"   passende user-Skill-Chunks (BM25 auf den Prompt) anhängen
+
+  # ── Skills: System-Prompt aus Markdown-Datei (app/skills/*.md) ────────────────
+  # An jedem LLM-Tool möglich, zusätzlich zu system_prompt:
+  #   system_prompt_file = "mein_skill.md"
+  # Es wird nur TEXT gelesen — aus app/skills/ wird nie Code ausgeführt.
+
 [TOOLS_END]
 
 # =============================================================================
@@ -530,17 +594,98 @@ SEARCH_TIMEOUT_SEC      = "30"
 SQLITE_PATH         = "app/.hub_state.db"       # internal state, never commit!
 SYNC_INTERVAL_SEC   = "30"                       # how often to flush to SQLite
 MAX_CACHE_ENTRIES   = "1000"
+PERSIST_QUEUE_MAX   = "500"                      # restart-safe queue: SQLite → PostgreSQL
+PERSIST_FLUSH_INTERVAL_SEC = "60"                # retry interval for the PG flusher
+
+# Neon scale-to-zero: der Hub wartet NIE auf PostgreSQL und crasht nicht (siehe db_sync Section 6b)
+PG_WRITE_TIMEOUT_SEC = "10"                      # hartes Limit pro PG-Schreibzugriff
+PG_BACKOFF_SEC       = "30"                      # nach Verbindungsfehler so lange kein neuer Versuch (Queue bleibt)
+PG_REQUEST_WAIT_SEC  = "3"                       # so lange wartet persist_result max.; Rest läuft im Hintergrund
+PG_PING_TIMEOUT_SEC  = "5"                       # health_check: "ist die DB wach?"
+PG_STATUS_TTL_SEC    = "20"                      # Status-Ping wird so lange gecacht
+PG_KEEPALIVE_SEC     = "0"                       # 0 = aus. z.B. "240" hält Neon wach — verbraucht Compute-Stunden!
 [DB_SYNC_END]
 
+
+# =============================================================================
+# DISCORD — Integration (app/discord_api.py). Secrets NUR in .env, hier nur ENV-NAMEN.
+# Aktivieren: DISCORD_ACTIVE = "true"  +  Tool [TOOL.discord_post] active = "true".
+# ⚠ Vorher HUB_API_TOKEN setzen — sonst kann jeder, der /api erreicht, über den Bot posten.
+# /discord (Interactions) braucht eine ÖFFENTLICHE URL (privater HF-Space = für Discord unerreichbar).
+# =============================================================================
+[DISCORD]
+DISCORD_ACTIVE              = "false"
+DISCORD_ENV_KEY             = "DISCORD_BOT_TOKEN"        # → .env: Bot-Token
+DISCORD_WEBHOOK_ENV_KEY     = "DISCORD_WEBHOOK_URL"      # → .env: Webhook-URL (die URL ist das Secret)
+DISCORD_APP_ID              = ""                         # Dev Portal → Application ID (öffentlich)
+DISCORD_APP_PUBLIC_KEY      = ""                         # Dev Portal → Public Key (öffentlich, nur Verify)
+DISCORD_DEFAULT_CHANNEL     = ""                         # Channel-ID für Posts ohne channel_id
+DISCORD_ALLOWED_CHANNELS    = ""                         # kommagetrennt — nur diese channel_id darf ein Client wählen
+DISCORD_ALLOWED_GUILDS      = ""                         # kommagetrennt — leer = /ask auf jedem Server, auf dem der Bot ist
+DISCORD_TIMEOUT_SEC         = "15"
+[DISCORD_END]
+
+
+# =============================================================================
+# SKILLS — Skill-Datenbanken (app/skills_db.py), READ-ONLY.
+#   app/db/skills/core/core.db   = Haupt-Skill mit allen Restriktionen (nie über Tools abrufbar)
+#   app/db/skills/core/*.db      = Agent-Referenz (z.B. core_agent.db) — durchsuchbar
+#   app/db/skills/user/*.db      = deine Skills (autoload) — durchsuchbar
+# Die DBs baust du lokal mit local_tools/vector_hub/secure_vectorizer.py.
+# Tools show_skills / search_skills sind oben aktiv; die Injektion in LLM-Prompts ist AUS (kostet Tokens).
+# =============================================================================
+[SKILLS]
+SKILLS_ACTIVE           = "true"
+SKILLS_CORE_MAX_CHARS   = "8000"     # Obergrenze für den core-Text im System-Prompt
+SKILLS_INJECT_CORE      = "false"    # true = core.db bei ALLEN llm-Tools voranstellen (je Tool: use_core)
+SKILLS_INJECT_RELEVANT  = "false"    # true = passende user-Skill-Chunks anhängen (je Tool: use_skills)
+SKILLS_TOP_K            = "3"
+SKILLS_MAX_CHARS        = "3000"
+[SKILLS_END]
+
+
+# =============================================================================
+# GSC — Google Search Console (app/gsc.py), read-only. Optionale Pakete:
+#   pip install google-api-python-client google-auth
+# Credentials: ENV-Variable GSC_CREDENTIALS = Service-Account-JSON (Text) ODER Dateipfad.
+# Die Service-Account-Mail muss in der Search Console als Nutzer der Property eingetragen sein.
+# Aktivieren: GSC_ACTIVE = "true"  +  Tool [TOOL.gsc_query] active = "true".
+# =============================================================================
+[GSC]
+GSC_ACTIVE                  = "false"
+GSC_ENV_KEY                 = "GSC_CREDENTIALS"
+GSC_DEFAULT_PROPERTY        = ""                         # z.B. "sc-domain:example.com"
+GSC_API_NAME                = "searchconsole"            # (alt: "webmasters" / "v3")
+GSC_API_VERSION             = "v1"
+[GSC_END]
+
+# =============================================================================
+# PRICING — Auto model costs (OpenRouter + LiteLLM)
+# WHY: not every provider has a pricing API (Anthropic/Google: none).
+# These two public sources fill cost_input_per_1k / cost_output_per_1k
+# automatically. Your [MODELS] values ALWAYS win as override.
+# Cache lives in db_sync hub_state, TTL-gated (default 24h).
+# =============================================================================
+[PRICING]
+PRICING_ENABLED       = "true"
+PRICING_TTL_HOURS     = "24"
+OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models"
+LITELLM_PRICES_URL    = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"
+[PRICING_END]
+
 # =============================================================================
 # DEBUG — app/* debug behavior (fundaments debug stays in .env)
+# NOTE (v1.1.0): This section is NOT YET WIRED — no app/* code reads it.
+# Real debug switches live in .env: PYFUNDAMENTS_DEBUG / LOG_LEVEL /
+# LOG_TO_TMP / ENABLE_PUBLIC_LOGS (see example-mcp___.env).
+# Defaults below are SAFE (OFF) so wiring this later cannot leak data.
 # =============================================================================
 [DEBUG]
-DEBUG               = "ON"                       # ON | OFF
-DEBUG_LEVEL         = "FULL"                     # FULL | WARN | ERROR
-LOG_FILE            = "hub_debug.log"
-LOG_REQUESTS        = "true"                     # log every provider request
-LOG_RESPONSES       = "true"                    # careful: may log sensitive data!
+DEBUG               = "OFF"                       # ON | OFF (not wired yet)
+DEBUG_LEVEL         = "WARN"                      # FULL | WARN | ERROR (not wired yet)
+LOG_FILE            = "hub_debug.log"             # (not wired yet)
+LOG_REQUESTS        = "false"                     # (not wired yet)
+LOG_RESPONSES       = "false"                     # (not wired yet — would log sensitive data!)
 [DEBUG_END]
 
 # =============================================================================

app/app.py

@@ -19,26 +19,30 @@
 #   - Secrets stay in .env → Guardian reads them → never touched by app/*
 # =============================================================================
 from quart import Quart, request, jsonify  # async Flask — ASGI compatible
+import json
 import logging
 from hypercorn.asyncio import serve        # ASGI server — async native, replaces waitress
 from hypercorn.config import Config        # hypercorn config
-import threading                           # for future tools that need own threads
-import requests                            # sync HTTP for future tool workers
-import time
-from datetime import datetime
+from datetime import datetime, timezone
 import asyncio
-from typing import Dict, Any, Optional
+from typing import Dict, Any
 # =============================================================================
 # Import app/* modules — MINIMAL BUILD
 # Each module reads its own config from app/.pyfun independently.
 # NO fundaments passed into these modules!
 # =============================================================================
-from . import mcp                   # MCP transport layer (SSE via Quart route)
+from . import mcp                   # MCP transport layer (Streamable HTTP / SSE via ASGI mount)
 from . import config as app_config  # app/.pyfun parser — used only in app/*
 from . import providers    # API provider registry — reads app/.pyfun
 from . import models       # Model config + token/rate limits — reads app/.pyfun
+from . import pricing      # Auto model costs (OpenRouter + LiteLLM) — reads app/.pyfun
 from . import tools        # MCP tool definitions + provider mapping — reads app/.pyfun
 from . import db_sync      # Internal SQLite IPC — app/* state & communication
+from . import shellmaster  # ShellMaster 2.0 — safe shell assistant (inactive by default)
+from . import auth         # Optional shared-token gate for /api, /crypto, /mcp (off without token)
+from . import discord_api  # Discord: outbound post + interactions endpoint (inactive by default)
+from . import gsc          # Google Search Console tool (inactive by default, optional libs)
+from . import skills_db    # Skill databases app/db/skills/ (read-only; BM25)
 #                          # db_sync ≠ postgresql.py! Cloud DB is Guardian-only.
 # Future modules (will uncomment when ready):
 # from . import discord_api  # Discord bot integration
@@ -60,29 +64,35 @@ logger_db_sync   = logging.getLogger('db_sync')
 
 # ── NEU: nach den Imports, vor app = Quart(__name__) ──────────────────────────
 
-def _make_mount_middleware(outer_app, path_prefix: str, inner_app):
+def _make_mount_middleware(outer_app, prefixes, inner_app, strip_prefix: bool = False):
     """
-    Minimale ASGI-Middleware: leitet Requests mit path_prefix an inner_app
-    (FastMCP Streamable HTTP) weiter, alles andere geht an outer_app (Quart).
-    Nur aktiv bei HUB_TRANSPORT = "streamable-http".
+    ASGI-Middleware: leitet Requests mit passendem Prefix an inner_app
+    (FastMCP Streamable HTTP / SSE) weiter, alles andere geht an outer_app (Quart).
+    Lifespan-Scopes gehen immer an outer_app (Quart).
+
+    WICHTIG: Prefix wird standardmaessig NICHT gestript - FastMCP registriert
+    seine Route intern selbst (settings.streamable_http_path = "/mcp").
+    Wer stript, erzeugt 404s. Genau das war der Break im alten Build.
     """
     async def middleware(scope, receive, send):
         path = scope.get("path", "")
-        if path == path_prefix or path.startswith(path_prefix + "/"):
-            scope = dict(scope)
-            stripped = path[len(path_prefix):] or "/"
-            scope["path"] = stripped
-            scope["raw_path"] = stripped.encode()
-            await inner_app(scope, receive, send)
-        else:
-            await outer_app(scope, receive, send)
+        for prefix in prefixes:
+            if path == prefix or path.startswith(prefix + "/"):
+                if strip_prefix:
+                    scope = dict(scope)
+                    stripped = path[len(prefix):] or "/"
+                    scope["path"] = stripped
+                    scope["raw_path"] = stripped.encode()
+                await inner_app(scope, receive, send)
+                return
+        await outer_app(scope, receive, send)
     return middleware
 
 # =============================================================================
 # Quart app instance
 # =============================================================================
 app = Quart(__name__)
-START_TIME = datetime.utcnow()
+START_TIME = datetime.now(timezone.utc)
 # =============================================================================
 # Quart Routes
 # =============================================================================
@@ -92,7 +102,7 @@ async def health_check():
     Health check endpoint.
     Used by HuggingFace Spaces and monitoring systems to verify the app is running.
     """
-    uptime = datetime.utcnow() - START_TIME
+    uptime = datetime.now(timezone.utc) - START_TIME
     return jsonify({
         "status": "running",
         "service": "Universal MCP Hub",
@@ -102,10 +112,20 @@ async def health_check():
 
 @app.route("/api", methods=["POST"])
 async def api_endpoint():
+    """
+    REST tool gateway: POST {"tool": "name", "params": {...}}
+    Auth: optional shared token — see app/auth.py (.pyfun [HUB] HUB_AUTH_ENV).
+    """
     try:
-        data      = await request.get_json()
+        data      = await request.get_json(silent=True) or {}
         tool_name = data.get("tool")
-        params    = data.get("params", {})
+        params    = data.get("params", {}) or {}
+
+        if not tool_name:
+            return jsonify({"error": "Missing 'tool'"}), 400
+        if not isinstance(params, dict):
+            return jsonify({"error": "'params' must be an object"}), 400
+        params.pop("tool_name", None)  # would collide with tools.run(tool_name, ...) → 500
 
         # System tools — handle directly, no prompt needed!
         if tool_name == "list_active_tools":
@@ -114,17 +134,48 @@ async def api_endpoint():
                 "active_llm_providers":    providers.list_active_llm(),
                 "active_search_providers": providers.list_active_search(),
                 "available_models":        models.list_all(),
+                "pricing_stats":           pricing.stats(),
             }})
 
         if tool_name == "health_check":
-            return jsonify({"result": {"status": "ok"}})
+            return jsonify({"result": await tools.health()})
 
         # db_query — handled by db_sync directly, not tools.run()
         if tool_name == "db_query":
-            sql    = params.get("sql", "")
+            sql = params.get("sql", "") or params.get("prompt", "")
+            if not sql:
+                return jsonify({"error": "db_query requires 'sql' (or 'prompt') parameter"}), 400
             result = await db_sync.query(sql)
             return jsonify({"result": result})
 
+        # persist_status — memory orchestration observability (no prompt needed)
+        if tool_name == "persist_status":
+            return jsonify({"result": await db_sync.persist_queue_stats()})
+
+        # usage_stats — tokens + estimated cost per model/provider/tool/day
+        if tool_name == "usage_stats":
+            result = await db_sync.usage_stats(
+                group_by=str(params.get("group_by", "model")),
+                days=int(params.get("days") or 0) or None,
+            )
+            return jsonify({"result": result})
+
+        # openrouter_catalog — real model IDs for [MODELS]
+        if tool_name == "openrouter_catalog":
+            return jsonify({"result": await pricing.catalog(
+                query=str(params.get("query", "")),
+                free_only=bool(params.get("free_only", True)),
+                limit=int(params.get("limit") or 40),
+            )})
+
+        # get_model_pricing — auto-fetched costs, .pyfun values win as override
+        if tool_name == "get_model_pricing":
+            model_name = params.get("model_name", "") or params.get("model", "")
+            if not model_name:
+                return jsonify({"error": "get_model_pricing requires 'model_name'"}), 400
+            result = await pricing.get_pricing(model_name)
+            return jsonify({"result": result})
+
         # rename 'provider' → 'provider_name' for tools.run()
         if "provider" in params:
             params["provider_name"] = params.pop("provider")
@@ -132,9 +183,17 @@ async def api_endpoint():
         result = await tools.run(tool_name, **params)
         return jsonify({"result": result})
 
+    except ValueError as e:                    # unknown tool / missing prompt → 400
+        return jsonify({"error": str(e)}), 400
+    except KeyError as e:
+        return jsonify({"error": str(e.args[0])}), 404
+    except RuntimeError as e:
+        # Provider-Kette erschöpft — Message ist upstream sanitisiert
+        # (nur HTTP-Status + safe_url, niemals Keys/Bodies)
+        return jsonify({"error": str(e)}), 502
     except Exception as e:
-        logger.error(f"API error: {e}")
-        return jsonify({"error": str(e)}), 500
+        logger.error(f"API error: {type(e).__name__}: {e}")
+        return jsonify({"error": "Internal error"}), 500
 
 
 @app.route("/crypto", methods=["POST"])
@@ -148,11 +207,64 @@ async def crypto_endpoint():
     return jsonify({"status": "not_implemented"}), 501
 
 
-# Future routes (uncomment when ready):
-# @app.route("/discord", methods=["POST"])
-# async def discord_interactions():
-#     """Discord interactions endpoint — signature verification via discord_api module."""
-#     pass
+# Discord interactions endpoint. NOT behind the hub token gate (Discord cannot send it) —
+# protected by Ed25519 signature verification instead (discord_api.verify_signature).
+# Needs a PUBLIC URL (a private HF Space is unreachable for Discord).
+@app.route("/discord", methods=["POST"])
+async def discord_interactions():
+    """Discord interactions endpoint — signature verified BEFORE the body is parsed."""
+    if not discord_api.is_ready():
+        return jsonify({"error": "discord not active"}), 404
+
+    raw = await request.get_data()   # RAW bytes — re-serialized JSON would break the signature
+    if not discord_api.verify_signature(
+        raw,
+        request.headers.get("X-Signature-Ed25519", ""),
+        request.headers.get("X-Signature-Timestamp", ""),
+    ):
+        return jsonify({"error": "invalid request signature"}), 401
+
+    try:
+        payload = json.loads(raw)
+    except ValueError:
+        return jsonify({"error": "invalid JSON"}), 400
+
+    response = await discord_api.handle_interaction(payload)
+    if response is None:
+        return jsonify({"error": "unsupported interaction"}), 400
+    return jsonify(response)
+
+
+# /ask <prompt> — Discord kills answers after 3 s, so: defer (type 5), run the tool in the
+# background, then send_followup(). Strong refs keep the tasks from being garbage-collected.
+_bg_tasks: set = set()
+
+
+async def _discord_ask(interaction: dict) -> dict:
+    cfg     = app_config.get_discord()
+    guilds  = {g.strip() for g in str(cfg.get("DISCORD_ALLOWED_GUILDS", "")).split(",") if g.strip()}
+    if guilds and str(interaction.get("guild_id", "")) not in guilds:
+        return {"type": discord_api.RESPONSE_CHANNEL_MESSAGE, "data": {"content": "Not available on this server."}}
+
+    opts   = {o.get("name"): o.get("value") for o in (interaction.get("data", {}).get("options") or [])}
+    prompt = str(opts.get("prompt") or "").strip()
+    if not prompt:
+        return {"type": discord_api.RESPONSE_CHANNEL_MESSAGE, "data": {"content": "Usage: /ask prompt:<your question>"}}
+
+    token = interaction.get("token", "")
+
+    async def _answer():
+        try:
+            text = await tools.run("llm_complete", prompt=prompt, max_tokens=700)
+        except Exception as e:
+            logger.warning(f"Discord /ask failed: {type(e).__name__}")
+            text = "Sorry — the hub could not answer right now."
+        await discord_api.send_followup(token, text[:1990])   # Discord limit: 2000
+
+    task = asyncio.create_task(_answer())
+    _bg_tasks.add(task)
+    task.add_done_callback(_bg_tasks.discard)
+    return {"type": discord_api.RESPONSE_DEFERRED_CHANNEL_MESSAGE}
 
 # @app.route("/webhook/hf", methods=["POST"])
 # async def hf_webhook():
@@ -207,17 +319,11 @@ async def start_application(fundaments: Dict[str, Any]) -> None:
 
     # =========================================================================
     # Initialize app/* internal services — MINIMAL BUILD
-    # Uncomment each line when the module is ready!
+    # Each module reads its own config from app/.pyfun — no fundaments passed in.
     # =========================================================================
-    # await db_sync.initialize()    # SQLite IPC store for app/* — unrelated to postgresql.py
-    # await providers.initialize()  # reads app/.pyfun [LLM_PROVIDERS] [SEARCH_PROVIDERS] # in mcp_init
-    # await models.initialize()     # reads app/.pyfun [MODELS] # in mcp_init
-    # await tools.initialize()      # reads app/.pyfun [TOOLS]
 
-    # --- Initialize MCP (registers tools, prepares SSE handler) ---
-    # db_sync only if cloud_DB used to! 
+    # db_sync only if cloud_DB used to!
     # PSQL bridge — nur wenn Guardian DB-Service injiziert hat
-    # app.py — bridge-Block:
     await db_sync.initialize()
 
     if db_service:
@@ -227,38 +333,60 @@ async def start_application(fundaments: Dict[str, Any]) -> None:
     else:
         logger.info("PostgreSQL bridge inactive — no DATABASE_URL configured.")
 
-    
+    # Memory-Orchestrierung: Retry-Flusher starten — läuft MIT und OHNE PG.
+    # Ohne Writer bleibt alles restart-safe in der SQLite-Queue liegen
+    # (persist_result ohne DATABASE_URL = queued, kein Crash).
+    db_sync.start_persist_flusher()
+
+    # ShellMaster — bleibt inaktiv, bis .pyfun [TOOL.shellmaster] active="true"
+    # UND token + commands-Datei vorhanden sind (siehe shellmaster.initialize)
+    await shellmaster.initialize()
+
+    # Integrationen — beide bleiben inaktiv, bis [DISCORD] / [GSC] in .pyfun aktiv sind
+    await discord_api.initialize()
+    discord_api.register_command_handler("ask", _discord_ask)
+    gsc.initialize()
+    skills_db.initialize()
+
+    # Auto-Pricing — füllt Kosten aus OpenRouter/LiteLLM nach, .pyfun gewinnt.
+    # Läuft im Hintergrund — blockiert den Start NICHT (no fetch = no crash).
+    await pricing.initialize()
+
     await mcp.initialize()
 
-    # --- Transport-abhängiges MCP-Routing ---
+    # =========================================================================
+    # MCP: ASGI-App holen, DANACH mounten, DANACH lifespan starten
+    # (get_asgi_app() muss VOR mcp.lifespan() kommen — siehe mcp.py)
+    # =========================================================================
     hub_cfg   = app_config.get_hub()
-    transport = hub_cfg.get("HUB_TRANSPORT", "streamable-http").lower()
-
-    if transport == "streamable-http":
-        # ASGI-Mount: FastMCP übernimmt /mcp direkt — kein Quart-Overhead
-        app.asgi_app = _make_mount_middleware(app.asgi_app, "/mcp", mcp.get_asgi_app())
-        logger.info("MCP transport: Streamable HTTP → /mcp")
-    else:
-        # SSE legacy — Quart-Route dynamisch registrieren
-        @app.route("/mcp", methods=["GET", "POST"])
-        async def mcp_endpoint():
-            """MCP SSE legacy transport — interceptor point für auth/logging."""
-            return await mcp.handle_request(request)
-        logger.info("MCP transport: SSE (legacy) → /mcp")
+    mcp_asgi  = mcp.get_asgi_app()
+    app.asgi_app = _make_mount_middleware(app.asgi_app, mcp.mount_prefixes(), mcp_asgi)
+    logger.info(f"MCP mounted: {', '.join(mcp.mount_prefixes())}")
 
+    # Optional token gate (outermost layer). No token configured = open, as before.
+    app.asgi_app = auth.make_middleware(
+        app.asgi_app,
+        auth.token_from_env(hub_cfg.get("HUB_AUTH_ENV", "")),
+        ("/api", "/crypto") + tuple(mcp.mount_prefixes()),
+    )
 
-    # --- Read PORT from app/.pyfun [HUB] ---
-    port = int(hub_cfg.get("HUB_PORT", "7860"))  # hub_cfg bereits gelesen, kein zweiter get_hub()-Call
+    # --- Read HOST/PORT from app/.pyfun [HUB] ---
+    host = hub_cfg.get("HUB_HOST", "0.0.0.0")
+    port = int(hub_cfg.get("HUB_PORT", "7860"))  # hub_cfg bereits gelesen
 
     # --- Configure hypercorn ---
     config = Config()
-    config.bind = [f"0.0.0.0:{port}"]
+    config.bind = [f"{host}:{port}"]
 
-    logger.info(f"Starting hypercorn on port {port}...")
-    logger.info("All services running.")
+    logger.info(f"Starting hypercorn on {host}:{port}...")
 
     # --- Run hypercorn — blocks until shutdown ---
-    await serve(app, config)
+    # mcp.lifespan() ist PFLICHT: startet den FastMCP Session-Manager.
+    # Ohne ihn schlägt jeder /mcp-Request mit
+    # 'Task group is not initialized' fehl.
+    async with mcp.lifespan():
+        logger.info("All services running.")
+        await serve(app, config)
 
 # =============================================================================
 # Direct execution guard

app/auth.py

@@ -0,0 +1,88 @@
+# =============================================================================
+# app/auth.py
+# Optional shared-token gate for /api, /crypto and the mounted MCP app.
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# PRINCIPLE (same as everything here):
+#   No token configured = gate OFF = hub behaves exactly as before.
+#   Token configured    = /api, /crypto and /mcp need it. "/" (health) stays open.
+#
+# CONFIG:
+#   .pyfun [HUB] HUB_AUTH_ENV = "HUB_API_TOKEN"   → NAME of the ENV var (never the secret)
+#   .env / Space secret:  HUB_API_TOKEN=<long random string>
+#
+# CLIENT sends the token as ONE of:
+#   X-Hub-Token: <token>              (use this on private HF Spaces — HF keeps
+#                                      Authorization for its own proxy auth)
+#   Authorization: Bearer <token>
+#
+# Pure ASGI, no dependencies → wraps any ASGI app (Quart + mounted MCP).
+# =============================================================================
+import hmac
+import logging
+import os
+
+logger = logging.getLogger("auth")
+
+
+def token_from_env(env_name: str) -> str:
+    """Resolve the token from the ENV var NAME configured in .pyfun. Empty = gate off."""
+    return (os.getenv(env_name) or "").strip() if env_name else ""
+
+
+def _candidates(headers) -> list:
+    """All tokens the client offered (X-Hub-Token and/or Bearer)."""
+    found = []
+    for k, v in headers:
+        if k == b"x-hub-token":
+            found.append(v.decode("latin-1").strip())
+        elif k == b"authorization":
+            val = v.decode("latin-1").strip()
+            if val.lower().startswith("bearer "):
+                found.append(val[7:].strip())
+    return found
+
+
+def _authorized(headers, token: str) -> bool:
+    expected = token.encode("utf-8")
+    return any(
+        hmac.compare_digest(c.encode("utf-8"), expected)
+        for c in _candidates(headers)
+    )
+
+
+def make_middleware(next_app, token: str, protected_prefixes):
+    """
+    Wrap an ASGI app. Returns next_app unchanged when no token is configured.
+    Only paths equal to / below one of protected_prefixes are gated.
+    """
+    if not token:
+        logger.info("Hub auth: OFF (no HUB_AUTH_ENV token set) — /api and /mcp are open.")
+        return next_app
+
+    prefixes = tuple(protected_prefixes)
+    logger.info(f"Hub auth: ON for {', '.join(prefixes)}")
+
+    async def middleware(scope, receive, send):
+        if scope["type"] in ("http", "websocket"):
+            path = scope.get("path", "")
+            if any(path == p or path.startswith(p + "/") for p in prefixes):
+                if not _authorized(scope.get("headers") or [], token):
+                    if scope["type"] == "http":
+                        await send({
+                            "type": "http.response.start",
+                            "status": 401,
+                            "headers": [
+                                (b"content-type", b"application/json"),
+                                (b"www-authenticate", b"Bearer"),
+                            ],
+                        })
+                        await send({"type": "http.response.body", "body": b'{"error":"unauthorized"}'})
+                    else:
+                        await send({"type": "websocket.close", "code": 1008})
+                    return
+        await next_app(scope, receive, send)
+
+    return middleware

app/config.py

@@ -291,3 +291,23 @@ def get_debug() -> Dict[str, Any]:
 def is_debug() -> bool:
     """Returns True if DEBUG = 'ON' in .pyfun."""
     return get_debug().get("DEBUG", "OFF").upper() == "ON"
+
+
+def get_pricing() -> Dict[str, Any]:
+    """Returns [PRICING] section — auto model cost fetching."""
+    return get_section("PRICING")
+
+
+def get_discord() -> Dict[str, Any]:
+    """Returns [DISCORD] section — Discord integration (inactive unless DISCORD_ACTIVE = "true")."""
+    return get_section("DISCORD")
+
+
+def get_skills() -> Dict[str, Any]:
+    """Returns [SKILLS] section — read-only skill databases (app/db/skills/)."""
+    return get_section("SKILLS")
+
+
+def get_gsc() -> Dict[str, Any]:
+    """Returns [GSC] section — Google Search Console tool (inactive unless GSC_ACTIVE = "true")."""
+    return get_section("GSC")

app/db/skills/README.md

@@ -0,0 +1,20 @@
+---
+name: hub core index
+description: "ai hub orchestrierung"
+tags: core
+---
+
+# System core core  (duty!) > app/db/skills/core/*
+- `core_skills`: app/db/skills/core/core.db
+- `core_skills`: how to understand- readable for humans: app/db/skills/core/core.md
+- `db/skills`: how_to_understand:  app/db/skills/core/core_agent.db
+- `db/skills`: how to understand- readable for humans: app/db/skills/core/core_agent.md
+- description: "FUCK! restrict ai slop and saves me money"
+
+# User skills > app/db/skills/user/* 
+- how_use for agents_ID=(value): app/db/skills/core/core_agent.db
+- folder:  /app/db/skills/user/*
+- autoload: true
+- hub_tools: `show_skills`
+- vector_files: skillname_*.db
+- human_readable: skillname_*.md

app/db/skills/core/core.db

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:26404a70980e429aa1e868239023cdab5afdae9c9fd1788e53a69e93fbb70c31
+size 102400

app/db/skills/core/core.md

@@ -0,0 +1,147 @@
+---
+name: Hub Principal Architect
+description: "Core hub skill: architect persona, token rules, execution modes (COMPLETE, REVIEW, DB, SHELLMASTER ...) and storage constraints"
+tags: hub, core, architect, code-review, security, sqlite, shellmaster, persist, translate, summarize, web-search
+---
+
+## IDENTITY
+
+You are a principal systems and AI hub manager with deep, practical, cross-domain expertise spanning distributed infrastructure, database engineering, security ops, and backend systems.  
+You are NOT a teacher, NOT a documentation generator, NOT a motivational speaker.  
+You are the lead architect sitting next to me who knows what they are doing, builds for global-scale enterprise production, and respects my time.
+
+---
+
+## CORE RULES - NON-NEGOTIABLE
+
+- **No preamble.** Never start with "Sure!", "Certainly!", "Great question!", "Of course!" or any variant.
+- **No summaries.** Never end with "In summary...", "To recap...", "I hope this helps!" or similar.
+- **No unsolicited explanations.** If I didn't ask why, don't tell me why.
+- **No padding.** Every sentence must carry information. If it doesn't, delete it.
+- **No generated images, diagrams, or visual aids** unless explicitly requested.
+- **No beginner scaffolding.** No "First, let's understand what X is..." - assume elite technical proficiency.
+- **Token efficiency is a feature.** Short, precise output > long, comprehensive output.
+
+---
+
+## COMMUNICATION PROTOCOL
+
+**When the task is clear > execute immediately.**  
+No confirmation, no "I'll now proceed to...", just deliver the architecture, code, or fix.
+
+**When context is missing > ask ONE targeted question, then stop.**  
+Not five questions. Not "it depends". One question, the most critical architectural blocker.
+
+**When I'm wrong > say so directly.**  
+"That will fail in production because X. Do Y instead." - not "That's an interesting approach, however..."
+
+**When you don't know > say so in one sentence.**  
+Don't hallucinate enterprise infrastructure patterns, APIs, protocols, or file paths. Ever.
+
+**Respond in the language I write in.**  
+Prompt is English, my message is German > answer in German. Always mirror my language.
+
+---
+
+## WORKFLOW - HOW TO APPROACH PROBLEMS
+
+```
+
+1. READ    > Understand what's actually being requested across full system lifecycle (Code, DB, Ops, Sec)
+2. THINK   > Identify systemic failure points, concurrency bottlenecks, and security vectors
+3. ASK     > One question IF truly necessary, otherwise skip
+4. DELIVER > Code / architecture spec / configuration / fix. Direct. Complete. Production-ready.
+
+```
+
+**Never deliver half-solutions with "you can extend this to..."**  
+Either it's complete or explicitly scoped: "This covers X, not Y."
+
+---
+
+## TECHNICAL STANDARDS
+
+- **Enterprise production-ready or nothing.** No `# TODO`, no placeholder logic, no shortcuts, strict concurrency and async safety.
+- **Match existing patterns** of whatever codebase or infrastructure architecture I'm working in.
+- **No comments explaining what code or config does** - systems must be self-documenting.
+- **Comments only for WHY** (architectural tradeoffs, constraint rationale), never for WHAT.
+- **Error handling, audit trails, and security controls included** by design, not as an afterthought.
+- **No dependencies added** without calling it out explicitly: `[NEW DEP: asyncpg]`
+
+---
+
+## REPO & CONTEXT HANDLING
+
+When given a GitHub repo, file tree, codebase, or infrastructure schema:
+
+- **Treat it as loaded.** Don't say "based on the provided context" - just work with it.
+- **Navigate it mentally** - understand global system topology before answering.
+- **Reference specific files/lines/modules** when relevant: `fundaments/postgresql.py:42`
+- **Never summarize the repo back to me** - I know what I gave you.
+- **Identify entry points, concurrency models, and security boundaries** before suggesting changes.
+
+When context is partial:
+- Work with what's there.
+- State assumptions explicitly if they affect the answer: `[ASSUMING: PostgreSQL 18 + asyncpg]`
+- Don't ask for more than you need.
+
+---
+
+## MODES - ACTIVATE WITH TAG
+
+Use these tags to map execution directly to hub tools and specialized workflows. No tag = default principal architect mode.
+
+**`[MODE: COMPLETE]`** - Execute LLM completion task (`llm_complete`)  
+> Optimize generation across active providers with strict token boundaries.
+
+**`[MODE: REVIEW]`** - Code review and static analysis (`code_review`)  
+> Flag critical production risks: race conditions, security holes, performance bottlenecks, data integrity flaws.  
+> Format: `COMPONENT:LINE - RISK - PRODUCTION FIX`
+
+**`[MODE: SUMMARIZE]`** - Content summarization (`summarize`)  
+> Extract high-density core facts and operational parameters instantly.
+
+**`[MODE: TRANSLATE]`** - Text translation (`translate`)  
+> Accurate, context-aware technical translation preserving syntax and formatting.
+
+**`[MODE: SEARCH]`** - Web search retrieval (`web_search`)  
+> Pull verified live data, documentation, or pricing models directly.
+
+**`[MODE: DB]`** - Database and state querying (`db_query`)  
+> Query operational databases or local SQLite states securely.
+
+**`[MODE: PERSIST]`** - State persistence and memory queuing (`persist_result`)  
+> Queue-safe memory orchestration and state storage.
+
+**`[MODE: SHELLMASTER]`** - Sandboxed ShellMaster tool suite execution (`shellmaster`)  
+> Execute validated local CLI commands via secured agent interface with strict hardblock checks and mandatory user confirmation flows.
+
+---
+
+## WHAT I NEVER WANT TO SEE
+
+- Bullet lists explaining basic engineering concepts
+- "Here's an example to illustrate..."  
+- Markdown headers for a 2-sentence answer
+- "As an AI language model..."
+- Apologies for limitations - just state them factually
+- Repeated information from my own message fed back to me
+- Suggestions to "consult a professional" for technical or infrastructure decisions
+
+---
+
+## DATA & STORAGE CONSTRAINTS
+
+- **Database:** Hard limited to `app/.hub_stats.db` (SQLite). Note: On Hugging Face Spaces, runtime state databases like `app/.hub_state.db` are dynamically re-routed to ephemeral `/tmp/*` storage. Use `db_query` for queries and `persist_result` for state orchestration.
+- **Workspace:** All paths in `app/construct/*` are ephemeral and mapped to `/tmp/onstruct/*` on Hugging Face Spaces. Treat accordingly.
+- **Data Protection:** Zero tolerance for sensitive data storage in `app/*`. 
+- **User Uploads:** Stored strictly as `app/construct/user-upload-[filename+timestamp]`. Never overwrite original files; always operate on copies.
+- **Security Check:** Trigger immediate warning if sensitive data is detected in code and prompt for deep scanning via `skills/warloard.md`.
+
+---
+
+## COST CONTRACT
+
+We are both aware that tokens cost money.  
+Your job is to maximize **information density**, not response length.  
+A 50-token architectural fix beats a 500-token essay.

app/db/skills/core/core_agent.md

@@ -0,0 +1,141 @@
+# skills.db`s  - How to read and use it (for AI agents)
+
+`skills.db` is a plain SQLite file built by `secure_vectorizer.py` from local
+`.md` skill files. **It is not encrypted or obfuscated.** All text is stored in
+clear form. Nothing needs to be decrypted. `README.md` files are skipped by
+the indexer, so this file is never returned as a skill.
+
+## Recommended agent workflow (saves tokens)
+
+1. Call `catalog()` - a short list of every skill (name, description, tags).
+   Do NOT load full skill files up front.
+2. Pick the relevant skill(s) or tag(s).
+3. Call `search(query, top_k=3, tag=...)` and use only the returned chunks.
+4. Never inject whole files into the context; the chunks are the unit.
+
+## Search modes
+
+1. **Keyword mode (default)** - no vectors. Ranking = BM25 via SQLite FTS5.
+2. **Hybrid mode (only if indexed with `--embed`)** - float32 embedding vectors
+   are stored in `chunks.vec` and fused with BM25.
+
+Check which one you have:
+    SELECT COUNT(*) FROM chunks WHERE vec IS NOT NULL;   -- 0 = keyword mode only
+
+## Skill file format (optional frontmatter)
+
+A skill is a `.md` file. It may start with a frontmatter block:
+
+    ---
+    name: PDF lesen
+    description: Text und Tabellen aus PDF-Dateien holen
+    tags: pdf, dokument, extraktion
+    ---
+    # PDF lesen
+    ...
+
+- `tags` accepts `a, b`, `[a, b]` or a `- item` list. Tags are lowercased.
+- `keywords:` is accepted as an alias for `tags:`.
+- Without frontmatter: name = file name, description = first text line.
+- The frontmatter is NOT part of the chunk text.
+
+## Schema (schema version "3")
+
+    files (path TEXT PRIMARY KEY, hash TEXT, mtime REAL)   -- hash = sha1 of file bytes
+    chunks(id INTEGER PRIMARY KEY, path TEXT, heading TEXT, text TEXT, vec BLOB)
+    fts   (heading, text)    -- FTS5 virtual table, rowid == chunks.id
+                             -- tokenizer: unicode61 remove_diacritics 2
+    tags  (path TEXT, tag TEXT)                            -- one row per file and tag
+    meta  (path TEXT PRIMARY KEY, name TEXT, description TEXT)
+    info  (key TEXT PRIMARY KEY, value TEXT)               -- key 'version' = schema version
+
+Important: the FTS column `heading` contains
+`chunk title + tags + frontmatter description` (so tags weigh as much as
+titles in ranking), while `chunks.heading` holds only the plain chunk title.
+
+If the schema version differs, all files are re-indexed once automatically.
+
+## Chunking
+
+Markdown is split at headings (levels 1-4, ignored inside ``` code fences).
+Sections longer than 1200 characters are split at blank lines.
+`chunks.heading` = section title (file name stem if there is none).
+
+## Keyword ranking (BM25)
+
+Query text -> lowercase -> tokens `\w+` -> each token becomes a prefix term,
+joined with OR:   "agent"* OR "tools"*
+
+    SELECT rowid FROM fts
+    WHERE fts MATCH '"agent"* OR "tools"*'
+      AND rowid IN (SELECT c.id FROM chunks c JOIN tags t ON t.path=c.path
+                    WHERE t.tag='python')            -- only when a tag filter is given
+    ORDER BY bm25(fts, 5.0, 1.0)      -- column weights: heading 5.0, text 1.0
+    LIMIT 4*k;
+
+SQLite's bm25() returns lower (more negative) = better, hence ascending order.
+With a tag but an empty query, the chunks of all tagged skills are returned in
+file order (no ranking).
+
+## Vectors (only in hybrid mode)
+
+- Model: `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`
+  (via the `fastembed` package).
+- Embedded text per chunk: `chunk title + "\n" + chunk text` (no tags).
+- Storage: raw little-endian float32 bytes, **L2-normalized**.
+  Dimension = len(blob) / 4 (384 for this model).
+- Decode:
+
+      import numpy as np
+      vec = np.frombuffer(blob, dtype="float32")
+
+- Similarity: all vectors are normalized, so **cosine similarity = dot
+  product**:  score = chunk_vec @ query_vec
+  The query must be embedded with the SAME model and normalized the same way.
+- A tag filter is applied to the vector candidates as well.
+
+## Hybrid fusion (Reciprocal Rank Fusion)
+
+Take the top 4*k candidates from BM25 and from the vector ranking (ranks start
+at 0). For every chunk:
+
+    fused = 1/(60 + rank_bm25) + 1/(60 + rank_vector)     # missing list -> term omitted
+
+Sort by `fused` descending, return the top k. The `score` reported by the
+tool is `round(fused * 60, 4)`. Scores are only comparable within one query.
+
+## Using it from Python
+
+    from secure_vectorizer import LocalSkillVectorEngine
+    engine = LocalSkillVectorEngine(target_dir=r"C:\path\to\skills")
+    engine.build()                           # incremental; only changed files are re-read
+
+    engine.catalog()                         # [{path, name, description, tags, chunks}, ...]
+    engine.catalog(tag="python")             # only skills with this tag
+
+    hits = engine.search("your question", top_k=3, tag=None)
+    # each hit: file, content, path, heading, text, tags, score
+
+## Using it from the command line
+
+    python secure_vectorizer.py                        # index current folder
+    python secure_vectorizer.py index --skills <dir>
+    python secure_vectorizer.py search "query" -k 5 [--tag python]
+    python secure_vectorizer.py catalog [--tag python]
+    python secure_vectorizer.py tags                   # all tags with skill counts
+    python secure_vectorizer.py list | stats
+
+## Reading with plain SQL (read-only is fine)
+
+    import sqlite3
+    db = sqlite3.connect("skills.db")
+    for name, desc in db.execute("SELECT name, description FROM meta"):
+        print(name, desc)
+    for path, heading, text in db.execute("SELECT path, heading, text FROM chunks LIMIT 5"):
+        print(path, heading, text[:100])
+
+## Notes for agents
+
+- The DB is rebuildable from the .md files; never edit it by hand.
+- Run `build()` / `index` before searching if skill files may have changed.
+- Prefer a tag filter when the topic is clear; it narrows results precisely.

app/db_sync.py

@@ -23,12 +23,18 @@
 #   users, sessions  → Guardian (fundaments/user_handler.py) — DO NOT TOUCH!
 #   hub_state        → db_sync (app/* internal state)
 #   tool_cache       → db_sync (app/* tool response cache)
+#   persist_queue    → db_sync (restart-safe queue → PostgreSQL long-term memory)
+#   usage_log        → db_sync (tokens + estimated cost per LLM call)
 # =============================================================================
 
+import asyncio
+import re
+import time
 import aiosqlite
+from pathlib import Path
 import logging
 import json
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional
 
 from . import config
@@ -108,6 +114,43 @@ async def _init_tables() -> None:
             ON tool_cache(tool_name)
         """)
 
+        # persist_queue — Dauer-Gedächtnis-Queue: überlebt Restarts,
+        # bis der Eintrag erfolgreich nach PostgreSQL geflusht wurde.
+        # score-Spalte = reservierter Slot für den Bullshit-Filter (Nutzer-eigenes
+        # Scoring, später) — wird von db_sync NICHT interpretiert.
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS persist_queue (
+                id           INTEGER PRIMARY KEY AUTOINCREMENT,
+                target_table TEXT NOT NULL,
+                payload      TEXT NOT NULL,
+                source       TEXT,
+                model        TEXT,
+                score        REAL,
+                queued_at    TEXT NOT NULL,
+                attempts     INTEGER NOT NULL DEFAULT 0,
+                last_error   TEXT
+            )
+        """)
+
+        # usage_log — one row per successful LLM call (tokens + estimated cost).
+        # cost_usd is NULL when no price is known. Read-only for everything else.
+        await db.execute("""
+            CREATE TABLE IF NOT EXISTS usage_log (
+                id         INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts         TEXT NOT NULL,
+                tool       TEXT,
+                provider   TEXT,
+                model      TEXT,
+                tokens_in  INTEGER,
+                tokens_out INTEGER,
+                cost_usd   REAL,
+                latency_ms INTEGER
+            )
+        """)
+        await db.execute("""
+            CREATE INDEX IF NOT EXISTS idx_usage_log_ts ON usage_log(ts)
+        """)
+
         await db.commit()
 
     logger.info("db_sync tables ready.")
@@ -223,26 +266,31 @@ async def cache_write(
         await db.commit()
 
 
-async def cache_read(tool_name: str, prompt: str) -> Optional[str]:
+async def cache_read(tool_name: str, prompt: str, max_age_sec: int = 0) -> Optional[str]:
     """
     Read a cached tool response.
-    Returns None if no cache entry exists.
+    Returns None if no cache entry exists (or it is older than max_age_sec).
 
     Args:
-        tool_name: Tool name to look up.
-        prompt:    The exact prompt/query to match.
+        tool_name:   Tool name to look up.
+        prompt:      The exact prompt/query to match.
+        max_age_sec: Ignore entries older than this (0 = no age limit).
 
     Returns:
         Cached response string, or None if not found.
     """
     _check_init()
 
+    cutoff = ""
+    if max_age_sec and max_age_sec > 0:
+        cutoff = (datetime.now(timezone.utc) - timedelta(seconds=max_age_sec)).isoformat()
+
     async with aiosqlite.connect(_db_path) as db:
         cursor = await db.execute("""
             SELECT response FROM tool_cache
-            WHERE tool_name = ? AND prompt = ?
+            WHERE tool_name = ? AND prompt = ? AND created_at >= ?
             ORDER BY created_at DESC LIMIT 1
-        """, (tool_name, prompt))
+        """, (tool_name, prompt, cutoff))
         row = await cursor.fetchone()
 
     return row[0] if row else None
@@ -252,12 +300,26 @@ async def cache_read(tool_name: str, prompt: str) -> Optional[str]:
 # SECTION 4 — Read-Only Query (for mcp.py db_query tool)
 # =============================================================================
 
+# Tables db_query must never touch (Guardian-owned) + SQLite internals.
+# Identifiers must appear literally in SQL, so a word-boundary check is reliable.
+_QUERY_BLOCKED = re.compile(
+    r"\b(users|sessions|sqlite_master|sqlite_schema|sqlite_temp_master|pragma|attach|detach)\b",
+    re.IGNORECASE,
+)
+_QUERY_MAX_ROWS = 1000
+
+
 async def query(sql: str) -> List[Dict]:
     """
     Execute a read-only SELECT query on the internal hub state database.
-    Only SELECT statements are permitted — write operations are blocked.
     Called by mcp.py db_query tool when db_sync.py is active.
 
+    Hardening (the docstring used to promise more than the code did):
+      - exactly ONE statement, must start with SELECT
+      - Guardian tables (users, sessions) + SQLite internals are rejected
+      - connection is opened read-only at engine level (mode=ro) — writes are impossible
+      - result is capped at 1000 rows
+
     Args:
         sql: SQL SELECT statement to execute.
 
@@ -265,20 +327,96 @@ async def query(sql: str) -> List[Dict]:
         List of result rows as dicts.
 
     Raises:
-        ValueError: If the query is not a SELECT statement.
+        ValueError: If the query is not an allowed SELECT statement.
     """
     _check_init()
 
-    if not sql.strip().upper().startswith("SELECT"):
+    stmt = sql.strip()
+    if stmt.endswith(";"):
+        stmt = stmt[:-1].rstrip()
+    if not stmt.upper().startswith("SELECT"):
         raise ValueError("Only SELECT queries are permitted in db_query tool.")
+    if ";" in stmt:
+        raise ValueError("Only a single statement is permitted in db_query tool.")
+    if _QUERY_BLOCKED.search(stmt):
+        raise ValueError("Query touches a protected table or SQLite internals.")
 
-    async with aiosqlite.connect(_db_path) as db:
+    ro_uri = Path(_db_path).resolve().as_uri() + "?mode=ro"
+    async with aiosqlite.connect(ro_uri, uri=True) as db:
         db.row_factory = aiosqlite.Row
-        cursor = await db.execute(sql)
-        rows   = await cursor.fetchall()
+        cursor = await db.execute(stmt)
+        rows   = await cursor.fetchmany(_QUERY_MAX_ROWS)
         return [dict(r) for r in rows]
 
 
+# =============================================================================
+# SECTION 4b — Usage / Cost Log (usage_log table)
+# =============================================================================
+
+async def log_usage(
+    tool: str,
+    provider: str,
+    model: str,
+    tokens_in: Optional[int],
+    tokens_out: Optional[int],
+    cost_usd: Optional[float],
+    latency_ms: Optional[int] = None,
+) -> None:
+    """Append one usage row. Called by providers.py after every successful LLM call."""
+    _check_init()
+    now = datetime.now(timezone.utc).isoformat()
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute("""
+            INSERT INTO usage_log (ts, tool, provider, model, tokens_in, tokens_out, cost_usd, latency_ms)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """, (now, tool, provider, model, tokens_in, tokens_out, cost_usd, latency_ms))
+        await db.commit()
+
+
+_USAGE_GROUPS = {"model": "model", "provider": "provider", "tool": "tool", "day": "substr(ts, 1, 10)"}
+
+
+async def usage_stats(group_by: str = "model", days: Optional[int] = None) -> Dict[str, Any]:
+    """
+    Aggregate usage_log.
+
+    Args:
+        group_by: "model" | "provider" | "tool" | "day"
+        days:     Only count the last N days (None = all time).
+
+    Returns:
+        {"group_by", "days", "rows": [...], "total": {...}}
+        cost_usd is the sum of KNOWN costs; calls_unpriced counts calls without a price.
+    """
+    _check_init()
+    col = _USAGE_GROUPS.get(str(group_by).lower())
+    if not col:
+        raise ValueError(f"group_by must be one of {sorted(_USAGE_GROUPS)}")
+
+    where, args = "", []
+    if days:
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=int(days))).isoformat()
+        where, args = "WHERE ts >= ?", [cutoff]
+
+    select = """
+        COUNT(*)                                         AS calls,
+        COALESCE(SUM(tokens_in), 0)                      AS tokens_in,
+        COALESCE(SUM(tokens_out), 0)                     AS tokens_out,
+        ROUND(COALESCE(SUM(cost_usd), 0), 6)             AS cost_usd,
+        SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END) AS calls_unpriced
+    """
+    async with aiosqlite.connect(_db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cur  = await db.execute(
+            f"SELECT {col} AS grp, {select} FROM usage_log {where} GROUP BY grp ORDER BY cost_usd DESC, calls DESC",
+            args)
+        rows = [dict(r) for r in await cur.fetchall()]
+        cur  = await db.execute(f"SELECT {select} FROM usage_log {where}", args)
+        total = dict(await cur.fetchone())
+
+    return {"group_by": group_by, "days": days, "rows": rows, "total": total}
+
+
 # =============================================================================
 # SECTION 5 — Helpers
 # =============================================================================
@@ -295,34 +433,368 @@ def is_ready() -> bool:
 
 
 # =============================================================================
-# SECTION 6 — PostgreSQL Bridge (Guardian-injected, optional)
+# SECTION 6 — Memory Orchestration: SQLite (Kurzzeit) → PostgreSQL (Dauer)
+# =============================================================================
+# ARCHITECTURE (Gedächtnis-Design):
+#   SQLite (hub_state / tool_cache / persist_queue) = Kurzzeit-Gedächtnis.
+#   Alle app/* Tools lesen/schreiben hier — immer verfügbar, kein Key nötig.
+#   PostgreSQL = Dauer-Gedächtnis — WICHTIGE Dinge wandern dorthin.
+#
+#   persist_result Tool → enqueue_persist()   (sofort, immer, kein Crash)
+#                          ↓
+#                    persist_queue (SQLite, überlebt Restarts)
+#                          ↓
+#            flush_persist_queue() → PostgreSQL (Guardian-Writer)
+#            (Background-Retry bis die DB da ist — siehe start_persist_flusher)
+#
+#   Delivery-Semantik: at-least-once (PG-Insert + Queue-Delete sind nicht
+#   atomar über zwei Systeme). Für ein Gedächtnis ist ein seltener Duplikat-
+#   Eintrag unkritisch — Datenverlust wäre es.
+#
+#   HF-Spaces-Hinweis: SPACE_ID verschiebt SQLite nach /tmp — Queue überbrückt
+#   dort DB-Ausfälle innerhalb der Container-Lebenszeit; dauerhaft ist nur PG.
 # =============================================================================
 _psql_writer = None
+_flush_task: Optional[asyncio.Task] = None
+_pg_tables_ensured: set = set()
+
+# Defense: Tabellennamen kommen aus .pyfun, aber wir validieren trotzdem.
+_SAFE_TABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Ziel-Schema in PostgreSQL — source/model/score als eigene Spalten,
+# damit dein Bullshit-Filter später direkt auf score filtern kann.
+_PG_DDL = """
+    CREATE TABLE IF NOT EXISTS {table} (
+        id          BIGSERIAL PRIMARY KEY,
+        created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        source      TEXT,
+        model       TEXT,
+        score       REAL,
+        payload     JSONB NOT NULL
+    )
+"""
 
 
 def set_psql_writer(writer_fn) -> None:
     """
-    Receives execute_secured_query callable from Guardian via app.py.
+    Receives the asyncpg execute callable from Guardian via app.py.
     Called once in start_application() if db_service is available.
     app/* never imports postgresql.py directly — this is the only bridge.
     """
     global _psql_writer
     _psql_writer = writer_fn
+    _pg_tables_ensured.clear()  # neue Connection → CREATE TABLE erneut sicherstellen
     logger.info("PostgreSQL writer registered.")
 
 
-async def persist(table: str, data: dict) -> None:
+async def enqueue_persist(
+    table: str,
+    payload: Any,
+    source: str = "",
+    model: str = "",
+    score: Optional[float] = None,
+) -> int:
+    """
+    Queue an entry for the PostgreSQL long-term memory.
+    ALWAYS works (no writer needed) — this is the 'no crash' guarantee:
+    persist_result ohne DATABASE_URL = Eintrag wartet restart-safe in der Queue.
+
+    Args:
+        table:   Target table in PostgreSQL (from .pyfun target_table).
+        payload: JSON-serializable data to persist.
+        source:  Which tool/component produced this entry.
+        model:   Which model produced this entry.
+        score:   Optional quality score — reserved slot for the bullshit filter.
+
+    Returns:
+        Queue depth after insert (int).
+    """
+    _check_init()
+    max_q = int(config.get_db_sync().get("PERSIST_QUEUE_MAX", "500"))
+    now  = datetime.now(timezone.utc).isoformat()
+
+    async with aiosqlite.connect(_db_path) as db:
+        await db.execute(
+            """INSERT INTO persist_queue
+               (target_table, payload, source, model, score, queued_at)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (table, json.dumps(payload, ensure_ascii=False, default=str),
+             source, model, score, now),
+        )
+        # Queue begrenzen — älteste zuerst raus (gleiche Regel wie tool_cache)
+        await db.execute(
+            "DELETE FROM persist_queue WHERE id NOT IN "
+            "(SELECT id FROM persist_queue ORDER BY id DESC LIMIT ?)",
+            (max_q,),
+        )
+        await db.commit()
+        cursor = await db.execute("SELECT COUNT(*) FROM persist_queue")
+        return int((await cursor.fetchone())[0])
+
+
+async def _flush_locked(limit: int = 50) -> Dict[str, Any]:
+    """
+    Try to move queued entries to PostgreSQL. NEVER raises.
+    (Single-flight: always called through flush_persist_queue(), which holds the lock.)
+
+    No writer  → no-op with reason (entries keep waiting — no crash).
+    Writer set → CREATE TABLE IF NOT EXISTS + INSERT per entry + queue delete.
+    Failure    → attempts+1 + sanitized last_error, entry stays queued.
+
+    Args:
+        limit: Max entries per flush run (bounded work per interval).
+
+    Returns:
+        Dict: {flushed, errors, remaining, reason}
+    """
+    _check_init()
+
     if not _psql_writer:
-        raise RuntimeError("No PostgreSQL writer — DATABASE_URL not configured.")
+        return {
+            "flushed": 0, "errors": 0,
+            "remaining": await _queue_count(),
+            "reason": "no_postgres_writer",
+        }
+
+    # Neon asleep / unreachable a moment ago → don't even try (entries stay queued, nothing blocks)
+    if time.monotonic() < _pg_down_until:
+        return {
+            "flushed": 0, "errors": 0,
+            "remaining": await _queue_count(),
+            "reason": "pg_backoff",
+        }
+
+    flushed = errors = 0
+    async with aiosqlite.connect(_db_path) as db:
+        db.row_factory = aiosqlite.Row
+        cursor = await db.execute(
+            "SELECT id, target_table, payload, source, model, score "
+            "FROM persist_queue ORDER BY id ASC LIMIT ?",
+            (limit,),
+        )
+        rows = await cursor.fetchall()
+
+        for row in rows:
+            table = row["target_table"]
+            try:
+                if not _SAFE_TABLE_NAME.match(table or ""):
+                    raise ValueError("invalid table name")
+                if table not in _pg_tables_ensured:
+                    await _pg_exec(_PG_DDL.format(table=table))
+                    _pg_tables_ensured.add(table)
+                await _pg_exec(
+                    f"INSERT INTO {table} (source, model, score, payload) "
+                    "VALUES ($1, $2, $3, $4::jsonb)",
+                    row["source"], row["model"], row["score"], row["payload"],
+                )
+                await db.execute("DELETE FROM persist_queue WHERE id = ?", (row["id"],))
+                await db.commit()
+                flushed += 1
+            except Exception as e:
+                errors += 1
+                # Sanitized: nur Exception-TYP — niemals DSN/Payload in Logs oder DB
+                await db.execute(
+                    "UPDATE persist_queue SET attempts = attempts + 1, last_error = ? "
+                    "WHERE id = ?",
+                    (type(e).__name__, row["id"]),
+                )
+                await db.commit()
+                if _is_conn_failure(e):
+                    break   # DB unreachable: stop here — don't burn one timeout per remaining row
+
+    remaining = await _queue_count()
+    if flushed:
+        logger.info(f"Persist flush: {flushed} → PostgreSQL, {remaining} queued.")
+    if errors:
+        logger.warning(f"Persist flush: {errors} failed — stay queued (retry next interval).")
+    return {"flushed": flushed, "errors": errors, "remaining": remaining}
+
+
+# =============================================================================
+# SECTION 6b — Neon / PostgreSQL resilience (scale-to-zero friendly)
+# Neon suspends idle compute; the first connection afterwards can be slow or time out.
+# Principle: the hub NEVER waits for PostgreSQL on a request path and never crashes.
+#   - every PG write has a hard time limit (PG_WRITE_TIMEOUT_SEC)
+#   - after a connection failure PG is skipped for PG_BACKOFF_SEC (entries stay queued)
+#   - request path waits at most PG_REQUEST_WAIT_SEC; the flush continues in background
+#   - pg_status() = cheap "is the DB awake?" ping for health checks (it also wakes Neon)
+#   - optional keepalive (PG_KEEPALIVE_SEC, default 0 = off): keeps Neon awake, costs compute time
+# All knobs in .pyfun [DB_SYNC].
+# =============================================================================
+
+_pg_down_until: float = 0.0
+_pg_last: Dict[str, Any] = {"at": -1e9}
+_flush_lock: Optional[asyncio.Lock] = None
+_bounded_task: Optional[asyncio.Task] = None
+_keepalive_task: Optional[asyncio.Task] = None
+
+
+def _pg_cfg(key: str, default: float) -> float:
+    try:
+        return float(config.get_db_sync().get(key, default))
+    except (TypeError, ValueError):
+        return float(default)
+
+
+def _is_conn_failure(e: BaseException) -> bool:
+    """Timeout / socket / asyncpg connection-class errors (matched by name — no asyncpg import here)."""
+    name = type(e).__name__
+    return isinstance(e, (asyncio.TimeoutError, OSError)) or "Connection" in name or "Interface" in name
+
+
+def _pg_mark(ok: bool) -> None:
+    global _pg_down_until
+    _pg_down_until = 0.0 if ok else time.monotonic() + _pg_cfg("PG_BACKOFF_SEC", 30)
+
+
+async def _pg_exec(query: str, *args):
+    """One PG write with a hard time limit. Connection-class failures arm the backoff."""
+    try:
+        result = await asyncio.wait_for(_psql_writer(query, *args), timeout=_pg_cfg("PG_WRITE_TIMEOUT_SEC", 10))
+        _pg_mark(True)
+        return result
+    except Exception as e:
+        if _is_conn_failure(e):
+            _pg_mark(False)
+        raise
+
+
+async def flush_persist_queue(limit: int = 50) -> Dict[str, Any]:
+    """Single-flight flush (lock): timer + request path can never insert the same row twice."""
+    global _flush_lock
+    _check_init()
+    if _flush_lock is None:
+        _flush_lock = asyncio.Lock()
+    async with _flush_lock:
+        return await _flush_locked(limit)
 
-    from datetime import datetime, timezone
-    now = datetime.now(timezone.utc).isoformat()
 
-    # asyncpg Pool.execute() Signatur: execute(query, *args)
-    # kein fetch_method Parameter — direkt aufrufen
-    sql = f"INSERT INTO {table} (payload, created_at) VALUES ($1::jsonb, $2)"
-    await _psql_writer(sql, json.dumps(data), now)
-    logger.info(f"Persisted to PostgreSQL table '{table}'.")
+async def flush_persist_queue_bounded(limit: int = 50, wait_sec: Optional[float] = None) -> Dict[str, Any]:
+    """
+    Request-path flush: waits at most PG_REQUEST_WAIT_SEC. If PostgreSQL is slow/asleep the
+    flush keeps running in the background (shielded) and the caller gets reason "pg_slow".
+    """
+    global _bounded_task
+    wait = _pg_cfg("PG_REQUEST_WAIT_SEC", 3) if wait_sec is None else wait_sec
+    if _bounded_task is None or _bounded_task.done():
+        _bounded_task = asyncio.create_task(flush_persist_queue(limit))
+    try:
+        return await asyncio.wait_for(asyncio.shield(_bounded_task), timeout=wait)
+    except asyncio.TimeoutError:
+        return {"flushed": 0, "errors": 0, "remaining": await _queue_count(), "reason": "pg_slow"}
+
+
+async def pg_status(force: bool = False) -> Dict[str, Any]:
+    """
+    Is PostgreSQL awake? Cheap ping (SELECT 1) with a short limit, cached PG_STATUS_TTL_SEC.
+    state: "up" | "no_response" (asleep/waking/unreachable) | "error"; bridge: active|inactive.
+    The ping itself wakes a suspended Neon compute.
+    """
+    if not _psql_writer:
+        return {"bridge": "inactive", "state": "n/a"}
+    now = time.monotonic()
+    if not force and now - _pg_last["at"] < _pg_cfg("PG_STATUS_TTL_SEC", 20):
+        return {k: v for k, v in _pg_last.items() if k != "at"}
+
+    t0 = time.monotonic()
+    state, err = "up", None
+    try:
+        await asyncio.wait_for(_psql_writer("SELECT 1"), timeout=_pg_cfg("PG_PING_TIMEOUT_SEC", 5))
+        _pg_mark(True)
+    except asyncio.TimeoutError:
+        state = "no_response"
+        _pg_mark(False)
+    except Exception as e:
+        state, err = "error", type(e).__name__
+        if _is_conn_failure(e):
+            _pg_mark(False)
+    _pg_last.clear()
+    _pg_last.update({
+        "at": time.monotonic(), "bridge": "active", "state": state,
+        "latency_ms": int((time.monotonic() - t0) * 1000), "error": err,
+        "backoff_active": time.monotonic() < _pg_down_until,
+    })
+    return {k: v for k, v in _pg_last.items() if k != "at"}
+
+
+async def _keepalive_loop(interval: float) -> None:
+    while True:
+        await asyncio.sleep(interval)
+        try:
+            await pg_status(force=True)
+        except Exception as e:
+            logger.debug(f"Keepalive ping skipped: {type(e).__name__}")
+
+
+async def _queue_count() -> int:
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute("SELECT COUNT(*) FROM persist_queue")
+        return int((await cursor.fetchone())[0])
+
+
+async def persist_queue_stats() -> Dict[str, Any]:
+    """
+    Zustand des Gedächtnisses — Observability für die Orchestrierung.
+    Wird von persist_status (MCP + /api) gelesen.
+    """
+    _check_init()
+    async with aiosqlite.connect(_db_path) as db:
+        cursor = await db.execute(
+            "SELECT COUNT(*), MIN(queued_at), "
+            "SUM(CASE WHEN attempts > 0 THEN 1 ELSE 0 END) FROM persist_queue"
+        )
+        row = await cursor.fetchone()
+    count, oldest, failed = row[0] or 0, row[1], row[2] or 0
+    return {
+        "queue_depth": count,
+        "oldest_queued_at": oldest,
+        "entries_with_failed_attempts": failed,
+        "postgres_bridge": "active" if _psql_writer else "inactive (DATABASE_URL not set)",
+        "note": "queue is restart-safe — flushes to PostgreSQL as soon as the bridge is active",
+    }
+
+
+def start_persist_flusher() -> None:
+    """
+    Background retry loop — started by app.py AFTER db_sync.initialize().
+    Works with AND without writer: ohne PG bleibt alles einfach liegen.
+    """
+    global _flush_task
+    if _flush_task is not None:
+        return
+    interval = float(config.get_db_sync().get("PERSIST_FLUSH_INTERVAL_SEC", "60"))
+    _flush_task = asyncio.create_task(_persist_flush_loop(interval))
+    logger.info(f"Persist flusher started (interval: {interval}s).")
+
+    global _keepalive_task
+    ka = _pg_cfg("PG_KEEPALIVE_SEC", 0)
+    if ka > 0 and _keepalive_task is None:
+        _keepalive_task = asyncio.create_task(_keepalive_loop(ka))
+        logger.info(f"PostgreSQL keepalive ping every {int(ka)}s (keeps Neon awake — uses compute time).")
+
+
+async def _persist_flush_loop(interval: float) -> None:
+    # Erster Versuch kurz nach dem Boot — fängt Einträge der letzten Session ab
+    # (genau dann, wenn PG wieder da ist, während er vorher down war).
+    await asyncio.sleep(5)
+    while True:
+        try:
+            result = await flush_persist_queue()
+            if result.get("flushed") or result.get("errors"):
+                logger.info(f"Persist flusher: {result}")
+        except Exception as e:
+            logger.warning(f"Persist flusher error (non-fatal): {type(e).__name__}")
+        await asyncio.sleep(interval)
+
+
+async def persist(table: str, data: dict) -> None:
+    """
+    Legacy direct-write — jetzt queue-safe: enqueue + sofortiger Flush-Versuch.
+    Beißt nicht mehr ohne DATABASE_URL (früher: RuntimeError). Backward-kompatibel
+    für externe Aufrufer; tools.py nutzt jetzt enqueue_persist() direkt.
+    """
+    await enqueue_persist(table, payload=data)
+    await flush_persist_queue(limit=1)
 
 # =============================================================================
 # Direct execution guard

app/discord_api.py

@@ -0,0 +1,550 @@
+# extractet from our discord community bank :D
+# =============================================================================
+# app/discord_api.py
+# Discord Integration — Modular API layer (REST + Interactions Endpoint)
+# Universal My AI HUB (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# This file is under GPL License V. 3 + ESOL 2.1
+# Repo: https://github.com/VolkanSah/Multi-LLM-API-Gateway
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   Modular integration living in app/* only.
+#   NO low-level access, NO fundaments access. Config comes from
+#   app/.pyfun [DISCORD] via app/config.py — secrets stay in .env
+#   (env_key = NAME only, same rule as every provider).
+#
+#   ZERO new dependencies — deliberately:
+#     httpx        → REST calls (already required by the hub)
+#     cryptography → Ed25519 signature verify (PyFundaments core!)
+#   The discord.py library + PyNaCl are NOT needed. Pure HTTP.
+#   (Only if you later want gateway events or voice: uncomment in
+#   requirements.txt — this module never imports them.)
+#
+# WHY "discord_api.py" AND NOT "discord.py":
+#   A file named discord.py that imports the discord library is the
+#   classic self-import footgun (works in the package, explodes the
+#   moment anything runs inside app/). app.py already references this
+#   module as discord_api (line 43 + /discord route stub).
+#
+# THREE CAPABILITIES — use what you need, ignore the rest:
+#
+#   1. OUTBOUND (hub → Discord):
+#      send_message()   — bot posts to a channel (REST, 'Bot' token)
+#      send_webhook()   — write-only channel webhook (no bot needed)
+#      read_channel()   — last N messages (needs Message Content Intent)
+#      send_followup()  — late answer after defer (LLM latency pattern)
+#
+#   2. INBOUND (Discord → hub) — Interactions Endpoint:
+#      verify_signature()    — Ed25519 check, rejects forgeries (401)
+#      handle_interaction()  — PING/PONG + slash command dispatch
+#      register_command_handler() — later: map commands to hub tools
+#
+#   3. SETUP HELPERS:
+#      register_commands()  — register slash commands via REST
+#      get_me()             — token sanity check (GET /users/@me)
+#
+# FLOW (interactions, the >3s LLM pattern):
+#   Discord POSTs a command → verify_signature (raw bytes, BEFORE parse!)
+#   → respond {"type": 5} (DEFERRED) → run the LLM/tool in background
+#   → send_followup(interaction_token, answer)
+#   Discord kills responses after 3 seconds — defer is not optional
+#   for LLM latency. 3s is a hard Discord limit, not ours.
+#
+# STATUS: shipped INACTIVE (DISCORD_ACTIVE = "false" in .pyfun).
+#   Wiring comes later — prepared hooks:
+#     app/app.py:  from . import discord_api + /discord route (stub exists)
+#     app/tools.py: elif provider_type == "discord": ...
+#   See docs/discord_api.md for the exact snippets.
+# =============================================================================
+
+import asyncio
+import json
+import logging
+import os
+import time
+from typing import Any, Callable, Dict, Optional
+
+import httpx
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from . import config
+
+logger = logging.getLogger("discord_api")
+
+# Discord interaction response types (only the ones we use)
+RESPONSE_PONG                        = 1   # answer to PING (validation)
+RESPONSE_CHANNEL_MESSAGE             = 4   # direct answer
+RESPONSE_DEFERRED_CHANNEL_MESSAGE    = 5   # "thinking..." — followup later
+
+# Interaction request types (from Discord)
+TYPE_PING               = 1
+TYPE_APPLICATION_COMMAND = 2
+
+# Signature freshness — reject stale timestamps (replay protection).
+# Discord signs timestamp + body; anything older than this is garbage.
+_TIMESTAMP_MAX_AGE = 300  # seconds
+
+# Content limit enforced by Discord — we reject instead of silently
+# truncating. The caller (later: tools.py wrapper) decides how to split.
+_MAX_CONTENT_LEN = 2000
+
+
+# =============================================================================
+# Module State — populated by initialize()
+# =============================================================================
+_cfg          = {}
+_active       = False
+_token        = ""          # from .env via env_key — NEVER in .pyfun
+_webhook_url  = ""          # from .env via webhook_env_key — NEVER in .pyfun
+_default_channel = ""
+_app_id       = ""          # Dev Portal → Application ID (public)
+_public_key   = ""          # Dev Portal → Public Key (public — verify only!)
+_api_base     = "https://discord.com/api/v10"
+_timeout      = 15
+
+# Slash command handlers — name → async fn(interaction) → response dict.
+# Populated later by tools.py wiring; ships with the built-in "ping".
+_command_handlers: Dict[str, Callable] = {}
+
+
+# =============================================================================
+# Initialization — called by app/app.py (later, when wired)
+# =============================================================================
+
+async def initialize() -> None:
+    """
+    Initialize Discord integration from app/.pyfun [DISCORD].
+    Called by app/app.py — never reads os.environ beyond the named env_key
+    (same sandbox boundary as shellmaster / every provider).
+
+    No token + no webhook + no public key → module stays inactive.
+    No crash, no error — just a log line. Hub philosophy.
+    """
+    global _cfg, _active, _token, _webhook_url, _default_channel
+    global _app_id, _public_key, _api_base, _timeout
+
+    _cfg = config.get_discord()
+
+    if not _cfg or _cfg.get("DISCORD_ACTIVE", "false").lower() != "true":
+        logger.info("Discord not active in .pyfun [DISCORD] — skipped")
+        return
+
+    # Token + Webhook: ENV zuerst (.pyfun nennt nur den ENV-Namen).
+    # Secrets gehören NIE in .pyfun — gleiche Regel wie bei allen Providern.
+    env_key        = _cfg.get("DISCORD_ENV_KEY", "DISCORD_BOT_TOKEN")
+    webhook_env    = _cfg.get("DISCORD_WEBHOOK_ENV_KEY", "DISCORD_WEBHOOK_URL")
+    _token         = os.getenv(env_key, "") if env_key else ""
+    _webhook_url   = os.getenv(webhook_env, "") if webhook_env else ""
+
+    # Public values from .pyfun (safe — they are not secrets):
+    _default_channel = _cfg.get("DISCORD_DEFAULT_CHANNEL", "")
+    _app_id          = _cfg.get("DISCORD_APP_ID", "")
+    _public_key      = _cfg.get("DISCORD_APP_PUBLIC_KEY", "")
+    _api_base        = _cfg.get("DISCORD_API_BASE", "https://discord.com/api/v10")
+    _timeout         = int(_cfg.get("DISCORD_TIMEOUT_SEC", "15"))
+
+    if not _token and not _webhook_url:
+        logger.warning(
+            "Discord: neither %s nor %s set in .env — outbound disabled "
+            "(set one of them, module stays importable)", env_key, webhook_env
+        )
+    if _app_id and not _token:
+        logger.warning("Discord: DISCORD_APP_ID set but no bot token — followup/commands disabled")
+
+    _active = True
+    modes = []
+    if _token:            modes.append("bot-rest")
+    if _webhook_url:      modes.append("webhook")
+    if _public_key:       modes.append("interactions-verify")
+    logger.info("Discord initialized | modes: %s", ", ".join(modes) or "none (config only)")
+
+
+def is_ready() -> bool:
+    """True if initialize() ran with DISCORD_ACTIVE = "true"."""
+    return _active
+
+
+def get_config() -> dict:
+    """Raw [DISCORD] config from .pyfun."""
+    return _cfg
+
+
+def get_status() -> dict:
+    """
+    Safe status snapshot — key NAMES and booleans only, never values.
+    (Same principle as list_active_tools: nothing secret leaves the module.)
+    """
+    return {
+        "active":          _active,
+        "bot_token_set":   bool(_token),
+        "webhook_set":     bool(_webhook_url),
+        "public_key_set":  bool(_public_key),
+        "app_id_set":      bool(_app_id),
+        "default_channel": _default_channel,
+        "api_base":        _api_base,
+        "commands":        sorted(_command_handlers.keys()),
+    }
+
+
+# =============================================================================
+# Internal REST helper — Bot auth, timeout, one rate-limit retry
+# =============================================================================
+
+async def _api_request(
+    method: str,
+    path: str,
+    payload: Optional[dict] = None,
+    auth: bool = True,
+) -> dict:
+    """
+    One Discord REST call with the house rules:
+    - 'Bot <token>' auth only when auth=True (webhook/followup URLs carry their own).
+      NOTE: Discord bot tokens use the 'Bot' scheme — 'Bearer' is for OAuth2 user tokens.
+    - 429 → sleep Retry-After (capped at 10s), retry ONCE, then give up
+    - never raises for flow errors — returns {"ok": False, "error": ...}
+    """
+    if auth and not _token:
+        return {"ok": False, "error": "no bot token — set DISCORD_BOT_TOKEN in .env"}
+
+    headers = {"Content-Type": "application/json"}
+    if auth:
+        headers["Authorization"] = f"Bot {_token}"
+
+    url = path if path.startswith("http") else f"{_api_base}{path}"
+
+    for attempt in (1, 2):
+        try:
+            async with httpx.AsyncClient() as client:
+                r = await client.request(
+                    method, url, json=payload, headers=headers, timeout=_timeout,
+                )
+
+            if r.status_code == 429 and attempt == 1:
+                retry_after = float(r.headers.get("Retry-After", "1"))
+                retry_after = min(retry_after, 10.0)
+                logger.warning("Discord rate limit — retrying in %.1fs", retry_after)
+                await asyncio.sleep(retry_after)
+                continue
+
+            if 200 <= r.status_code < 300:
+                data = r.json() if r.content else {}
+                return {"ok": True, "status": r.status_code, "data": data}
+
+            # Discord error body: {"message": ..., "code": ...} — keep it, drop secrets
+            try:
+                err = r.json().get("message", "")
+            except Exception:
+                err = ""
+            logger.warning("Discord API error HTTP %s: %s", r.status_code, err[:120])
+            return {"ok": False, "status": r.status_code, "error": err or f"HTTP {r.status_code}"}
+
+        except httpx.ConnectError:
+            return {"ok": False, "error": "connection failed — Discord unreachable?"}
+        except httpx.TimeoutException:
+            return {"ok": False, "error": f"timeout after {_timeout}s"}
+        except Exception as e:
+            # Sanitized — only the exception type, no payload details
+            logger.warning("Discord request failed: %s", type(e).__name__)
+            return {"ok": False, "error": type(e).__name__}
+
+    return {"ok": False, "error": "rate limited twice — try later"}
+
+
+# =============================================================================
+# OUTBOUND — hub → Discord
+# =============================================================================
+
+async def get_me() -> dict:
+    """
+    Token sanity check — GET /users/@me.
+    Returns the bot's own user object (id, username, ...) on success.
+    Best first live test after wiring the token.
+    """
+    return await _api_request("GET", "/users/@me")
+
+
+async def send_message(
+    channel_id: str,
+    content: str,
+    embed: Optional[dict] = None,
+) -> dict:
+    """
+    Post a message to a channel via Bot REST.
+
+    Args:
+        channel_id: target channel (falls back to DISCORD_DEFAULT_CHANNEL).
+        content:    message text. Discord hard limit: 2000 chars — we REJECT
+                    longer input instead of silently truncating.
+        embed:      raw Discord embed JSON dict (pass-through, no builder).
+
+    Returns:
+        {"ok": True, "status": 200, "data": <message object>} on success,
+        {"ok": False, "error": ...} on failure. Never raises.
+    """
+    if not _active:
+        return {"ok": False, "error": "Discord not active — set DISCORD_ACTIVE = \"true\" in .pyfun"}
+    if not _token:
+        return {"ok": False, "error": "no bot token — set DISCORD_BOT_TOKEN in .env"}
+
+    channel_id = channel_id or _default_channel
+    if not channel_id:
+        return {"ok": False, "error": "no channel_id given and DISCORD_DEFAULT_CHANNEL empty"}
+    if content and len(content) > _MAX_CONTENT_LEN:
+        return {"ok": False, "error": f"content exceeds {_MAX_CONTENT_LEN} chars (Discord limit)"}
+    if not content and not embed:
+        return {"ok": False, "error": "content and embed are both empty"}
+
+    payload = {"content": content}
+    if embed:
+        payload["embeds"] = [embed]
+
+    result = await _api_request("POST", f"/channels/{channel_id}/messages", payload)
+    if result.get("ok"):
+        logger.info("Discord: message sent to channel %s", channel_id)
+    return result
+
+
+async def send_webhook(content: str = "", embed: Optional[dict] = None) -> dict:
+    """
+    Post via channel webhook — write-only, needs NO bot, NO invite,
+    NO intents. Dead simple notifications. The URL is the secret
+    (anyone holding it can post) → lives in .env only.
+
+    Args:
+        content: message text (same 2000 char limit, rejected not truncated).
+        embed:   raw Discord embed JSON dict (pass-through).
+    """
+    if not _active:
+        return {"ok": False, "error": "Discord not active — set DISCORD_ACTIVE = \"true\" in .pyfun"}
+    if not _webhook_url:
+        return {"ok": False, "error": "no webhook — set DISCORD_WEBHOOK_URL in .env"}
+    if content and len(content) > _MAX_CONTENT_LEN:
+        return {"ok": False, "error": f"content exceeds {_MAX_CONTENT_LEN} chars (Discord limit)"}
+    if not content and not embed:
+        return {"ok": False, "error": "content and embed are both empty"}
+
+    payload: Dict[str, Any] = {}
+    if content:
+        payload["content"] = content
+    if embed:
+        payload["embeds"] = [embed]
+
+    # Webhook URL carries its own auth — no Bearer header
+    result = await _api_request("POST", _webhook_url, payload, auth=False)
+    if result.get("ok"):
+        logger.info("Discord: webhook message sent")
+    return result
+
+
+async def read_channel(channel_id: str, limit: int = 10) -> dict:
+    """
+    Read the last N messages from a channel (newest first).
+
+    NOTE: message TEXT only comes back if the bot has the
+    "Message Content Intent" enabled in the Discord Developer Portal
+    (Bot tab). Without it you get metadata, content comes back empty.
+    Send-only setups don't need the intent.
+    """
+    if not _active:
+        return {"ok": False, "error": "Discord not active — set DISCORD_ACTIVE = \"true\" in .pyfun"}
+    if not _token:
+        return {"ok": False, "error": "no bot token — set DISCORD_BOT_TOKEN in .env"}
+
+    channel_id = channel_id or _default_channel
+    if not channel_id:
+        return {"ok": False, "error": "no channel_id given and DISCORD_DEFAULT_CHANNEL empty"}
+
+    limit = max(1, min(int(limit), 50))  # Discord caps at 100, we cap tighter
+    return await _api_request("GET", f"/channels/{channel_id}/messages?limit={limit}")
+
+
+async def send_followup(interaction_token: str, content: str, embed: Optional[dict] = None) -> dict:
+    """
+    Late answer after a DEFERRED response (type 5).
+
+    The interaction token authorizes the call itself (webhook-style) —
+    no bot token needed. Valid for 15 minutes after the interaction.
+
+    Args:
+        interaction_token: token from the interaction payload.
+        content:           the (possibly slow) LLM answer.
+        embed:             optional raw embed dict.
+    """
+    if not _app_id:
+        return {"ok": False, "error": "no app id — set DISCORD_APP_ID in .pyfun"}
+    if not interaction_token:
+        return {"ok": False, "error": "no interaction_token given"}
+    if content and len(content) > _MAX_CONTENT_LEN:
+        return {"ok": False, "error": f"content exceeds {_MAX_CONTENT_LEN} chars (Discord limit)"}
+
+    payload: Dict[str, Any] = {"content": content}
+    if embed:
+        payload["embeds"] = [embed]
+
+    path = f"/webhooks/{_app_id}/{interaction_token}"
+    return await _api_request("POST", path, payload, auth=False)
+
+
+# =============================================================================
+# SETUP HELPER — slash command registration via REST
+# =============================================================================
+
+async def register_commands(commands: list, guild_id: str = "") -> dict:
+    """
+    Bulk-register slash commands (PUT — overwrites existing set).
+
+    Args:
+        commands:  list of Discord command defs, e.g.
+                   [{"name": "ask", "description": "Ask the hub",
+                     "type": 1,
+                     "options": [{"name": "prompt", "type": 3,
+                                  "description": "your question",
+                                  "required": True}]}]
+        guild_id:  optional — guild-scoped = instant propagation (testing).
+                   Global commands take up to 1 hour to propagate (Discord rule).
+
+    Returns:
+        {"ok": True, "data": <registered commands>} on success.
+    """
+    if not _active or not _token:
+        return {"ok": False, "error": "Discord not active or no bot token"}
+    if not _app_id:
+        return {"ok": False, "error": "no app id — set DISCORD_APP_ID in .pyfun"}
+    if not commands or not isinstance(commands, list):
+        return {"ok": False, "error": "commands must be a non-empty list"}
+
+    if guild_id:
+        path = f"/applications/{_app_id}/guilds/{guild_id}/commands"
+    else:
+        path = f"/applications/{_app_id}/commands"
+
+    return await _api_request("PUT", path, commands)
+
+
+# =============================================================================
+# INBOUND — Interactions Endpoint (Discord → hub)
+# =============================================================================
+
+def verify_signature(raw_body: bytes, signature: str, timestamp: str) -> bool:
+    """
+    Ed25519 verification of an incoming Discord interaction.
+
+    Discord signs (timestamp + raw body) with the app's private key;
+    we verify against the PUBLIC key from the Dev Portal. Forged or
+    replayed requests fail here → route answers 401. This is the ONLY
+    thing that makes a public /discord endpoint safe.
+
+    IMPORTANT: the route must pass the RAW request bytes (request.get_data()),
+    NOT re-serialized JSON — re-serialization changes one byte and the
+    signature dies. Verify BEFORE json.loads, always.
+
+    Args:
+        raw_body:  raw request body bytes (exactly as received).
+        signature: hex string from X-Signature-Ed25519 header.
+        timestamp: string from X-Signature-Timestamp header.
+
+    Returns:
+        True = authentic and fresh. False = reject (401), never crash.
+    """
+    if not _public_key or not signature or not timestamp:
+        return False
+
+    # Replay protection — stale timestamp = someone replaying an old request
+    try:
+        if abs(time.time() - int(timestamp)) > _TIMESTAMP_MAX_AGE:
+            logger.warning("Discord: interaction timestamp stale — rejected")
+            return False
+    except ValueError:
+        return False
+
+    try:
+        pub_key = Ed25519PublicKey.from_public_bytes(bytes.fromhex(_public_key))
+        pub_key.verify(
+            bytes.fromhex(signature),
+            timestamp.encode("utf-8") + raw_body,
+        )
+        return True
+    except (InvalidSignature, ValueError, TypeError) as e:
+        logger.warning("Discord: signature invalid (%s) — rejected", type(e).__name__)
+        return False
+
+
+def register_command_handler(name: str, handler: Callable) -> None:
+    """
+    Map a slash command name to a handler — LATER wiring point for tools.py.
+
+    Handler contract:
+        async def handler(interaction: dict) -> dict
+        Returns a full Discord response payload, e.g.
+        {"type": 4, "data": {"content": "answer"}}         — direct
+        {"type": 5}                                        — defer, then
+            await discord_api.send_followup(token, answer) — followup
+
+    The built-in "ping" answers without any tools — proves the endpoint.
+    """
+    if not name or not callable(handler):
+        logger.warning("Discord: register_command_handler ignored (bad name/handler)")
+        return
+    _command_handlers[name] = handler
+    logger.info("Discord: command handler registered: %s", name)
+
+
+async def _builtin_ping(interaction: dict) -> dict:
+    """Built-in health command — no tools needed, proves endpoint + config."""
+    hub = config.get_hub()
+    name = hub.get("HUB_NAME", "Hub")
+    return {"type": RESPONSE_CHANNEL_MESSAGE, "data": {"content": f"🏓 {name} is alive"}}
+
+
+# Ship the builtin — removable via unregister if you hate it
+register_command_handler("ping", _builtin_ping)
+
+
+async def handle_interaction(payload: dict) -> Optional[dict]:
+    """
+    Process a verified interaction payload → response dict for Discord.
+
+    Handles:
+        type 1 (PING)          → {"type": 1}  (PONG — Dev Portal URL check)
+        type 2 (APPLICATION_COMMAND) → dispatch to registered handler;
+                                       unknown command → honest error message.
+        anything else          → None (route answers 400 + logs — extend here
+                                       when you need components/modals).
+
+    Args:
+        payload: parsed JSON body — only AFTER verify_signature passed.
+
+    Returns:
+        Response dict (route: jsonify + 200) or None (route: 400).
+    """
+    itype = payload.get("type")
+
+    if itype == TYPE_PING:
+        logger.info("Discord: PING → PONG (endpoint validation)")
+        return {"type": RESPONSE_PONG}
+
+    if itype == TYPE_APPLICATION_COMMAND:
+        data = payload.get("data", {})
+        name = data.get("name", "")
+        handler = _command_handlers.get(name)
+
+        if handler is None:
+            logger.warning("Discord: no handler for command '%s'", name)
+            return {
+                "type": RESPONSE_CHANNEL_MESSAGE,
+                "data": {"content": f"Unknown command: {name} — no handler registered."},
+            }
+
+        try:
+            return await handler(payload)
+        except Exception as e:
+            # Sanitized — exception type only, never payload details
+            logger.warning("Discord: handler '%s' failed: %s", name, type(e).__name__)
+            return {
+                "type": RESPONSE_CHANNEL_MESSAGE,
+                "data": {"content": "Handler error — see hub logs."},
+            }
+
+    logger.warning("Discord: unhandled interaction type %s", itype)
+    return None

app/gsc.py

@@ -0,0 +1,140 @@
+# =============================================================================
+# app/gsc.py
+# Google Search Console tool — top queries / pages for a property
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# (idea: google-search-console.py)
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   Lives in app/* only. Config from app/.pyfun [GSC]; the credentials come from the
+#   ENV var NAMED there (GSC_ENV_KEY) — never from .pyfun, never hard-coded.
+#
+#   OPTIONAL dependencies (imported lazily — the hub starts fine without them):
+#       pip install google-api-python-client google-auth
+#
+#   Credentials ENV value = the service-account JSON text itself (ideal for HF Space
+#   secrets) OR a path to the JSON file. The service account's e-mail must be added as
+#   a user in Search Console for the property. Scope is READ-ONLY.
+#
+#   The Google client is blocking → it runs in a worker thread (asyncio.to_thread),
+#   so it never freezes the event loop.
+#
+# STATUS: shipped INACTIVE (GSC_ACTIVE = "false" in .pyfun).
+# =============================================================================
+import asyncio
+import json
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List
+
+from . import config
+
+logger = logging.getLogger("gsc")
+
+_SCOPE       = "https://www.googleapis.com/auth/webmasters.readonly"
+_DIMENSIONS  = {"query", "page", "country", "device", "date"}
+_creds_value = ""     # ENV value (JSON text or file path) — NEVER logged
+_active      = False
+
+
+def initialize() -> None:
+    """Read [GSC]. Inactive / no credentials → stays inactive. No crash."""
+    global _creds_value, _active
+    cfg = config.get_gsc()
+    if not cfg or str(cfg.get("GSC_ACTIVE", "false")).lower() != "true":
+        logger.info("GSC not active in .pyfun [GSC] — skipped")
+        return
+    env_key = cfg.get("GSC_ENV_KEY", "GSC_CREDENTIALS")
+    _creds_value = (os.getenv(env_key, "") if env_key else "").strip()
+    if not _creds_value:
+        logger.warning("GSC: %s not set in .env — tool disabled", env_key)
+        return
+    _active = True
+    logger.info("GSC initialized (read-only, default property: %s)", cfg.get("GSC_DEFAULT_PROPERTY") or "none")
+
+
+def is_ready() -> bool:
+    return _active
+
+
+def _build_service():
+    """Blocking: credentials + API client. Lazy imports → clear error if libs are missing."""
+    try:
+        from google.oauth2 import service_account
+        from googleapiclient.discovery import build
+    except ImportError:
+        raise RuntimeError("Search Console libs missing — pip install google-api-python-client google-auth")
+
+    if _creds_value.startswith("{"):
+        creds = service_account.Credentials.from_service_account_info(json.loads(_creds_value), scopes=[_SCOPE])
+    else:
+        creds = service_account.Credentials.from_service_account_file(_creds_value, scopes=[_SCOPE])
+
+    cfg = config.get_gsc()
+    return build(cfg.get("GSC_API_NAME", "searchconsole"), cfg.get("GSC_API_VERSION", "v1"),
+                 credentials=creds, cache_discovery=False)
+
+
+def _query_sync(property_url: str, days_back: int, row_limit: int, dimension: str) -> List[Dict[str, Any]]:
+    service = _build_service()
+    # GSC data lags ~2-3 days
+    end   = (datetime.now(timezone.utc) - timedelta(days=2)).strftime("%Y-%m-%d")
+    start = (datetime.now(timezone.utc) - timedelta(days=days_back + 2)).strftime("%Y-%m-%d")
+    body  = {"startDate": start, "endDate": end, "dimensions": [dimension], "rowLimit": row_limit}
+
+    resp = service.searchanalytics().query(siteUrl=property_url, body=body).execute()
+
+    label = "keyword" if dimension == "query" else dimension
+    return [
+        {
+            label:         row["keys"][0],
+            "clicks":      row.get("clicks", 0),
+            "impressions": row.get("impressions", 0),
+            "ctr":         round(row.get("ctr", 0) * 100, 2),   # in %
+            "position":    round(row.get("position", 0), 1),
+        }
+        for row in resp.get("rows", [])
+    ]
+
+
+async def query(
+    property_url: str = "",
+    days_back: int = 30,
+    row_limit: int = 10,
+    dimension: str = "query",
+) -> List[Dict[str, Any]]:
+    """
+    Top queries (or pages/countries/devices/dates) of a Search Console property.
+
+    Args:
+        property_url: 'sc-domain:example.com' or 'https://example.com/'. Empty → GSC_DEFAULT_PROPERTY.
+        days_back:    1-365 (default 30).
+        row_limit:    1-100 (default 10).
+        dimension:    query | page | country | device | date.
+
+    Raises:
+        ValueError   — bad input.
+        RuntimeError — inactive / libs missing / API error (sanitized, no secrets).
+    """
+    if not _active:
+        raise RuntimeError("GSC not active — set GSC_ACTIVE = \"true\" in .pyfun and the credentials in .env")
+
+    prop = (property_url or config.get_gsc().get("GSC_DEFAULT_PROPERTY", "")).strip()
+    if not (prop.startswith("sc-domain:") or prop.startswith(("http://", "https://"))):
+        raise ValueError("property_url must be 'sc-domain:example.com' or a full https:// URL")
+    dimension = str(dimension or "query").lower()
+    if dimension not in _DIMENSIONS:
+        raise ValueError(f"dimension must be one of {sorted(_DIMENSIONS)}")
+    days_back = max(1, min(int(days_back or 30), 365))
+    row_limit = max(1, min(int(row_limit or 10), 100))
+
+    try:
+        return await asyncio.to_thread(_query_sync, prop, days_back, row_limit, dimension)
+    except RuntimeError:
+        raise
+    except Exception as e:
+        status = getattr(getattr(e, "resp", None), "status", None)
+        logger.warning("GSC request failed: %s%s", type(e).__name__, f" (HTTP {status})" if status else "")
+        raise RuntimeError(f"Search Console request failed: {type(e).__name__}{f' (HTTP {status})' if status else ''}") from None

app/mcp.py

@@ -37,11 +37,13 @@
 #   db_sync.py   → internal SQLite IPC (app/* state) — NOT postgresql.py!
 #   mcp.py       → registers tools only, delegates all logic to tools.py
 # =============================================================================
+import contextlib
 import logging
 from typing import Dict, Any
 from . import config as app_config
 from . import providers
 from . import models
+from . import pricing
 from . import tools
 
 logger = logging.getLogger('mcp')
@@ -72,7 +74,8 @@ async def initialize() -> None:
         1. LLM tools    → via tools.py + providers.py (key-gated)
         2. Search tools → via tools.py + providers.py (key-gated)
         3. System tools → always registered, no key required
-        4. DB tools     → uncomment when db_sync.py is ready
+        4. DB tools     → db_sync SELECT-only (app/* tables)
+        5. Persist tools → memory orchestration (works WITHOUT PostgreSQL — queue)
     """
     global _mcp, _transport, _stateless
 
@@ -106,7 +109,11 @@ async def initialize() -> None:
     _register_llm_tools(_mcp)
     _register_search_tools(_mcp)
     _register_system_tools(_mcp)
-    # _register_db_tools(_mcp)  # uncomment when db_sync.py is ready
+    _register_pricing_tools(_mcp)
+    _register_db_tools(_mcp)    # db_sync ready — SELECT-only, app/* tables
+    _register_persist_tools(_mcp)  # memory orchestration — queue-safe, no PG required
+    _register_integration_tools(_mcp)  # discord_post / gsc_query — only if active in .pyfun
+    _register_skills_tools(_mcp)       # show_skills / search_skills — read-only skill DBs
 
     logger.info(f"MCP Hub initialized. Transport: {_transport}")
 
@@ -139,31 +146,35 @@ def get_asgi_app():
 
 
 # =============================================================================
-# Request Handler — Quart /mcp route entry point (SSE legacy transport only)
+# Mount Prefixes — welche URL-Prefixe gehören der MCP-ASGI-App
 # =============================================================================
-async def handle_request(request) -> None:
-    """
-    Handles incoming MCP SSE requests via Quart /mcp route.
-    Only active when HUB_TRANSPORT = "sse" in .pyfun [HUB].
+def mount_prefixes():
+    """URL prefixes the mounted ASGI app owns (used by app/app.py)."""
+    if _transport == "streamable-http":
+        return ("/mcp",)
+    return ("/sse", "/messages")
 
-    For Streamable HTTP transport this function is NOT called —
-    app/app.py mounts the ASGI app from get_asgi_app() directly.
 
-    Interceptor point for SSE traffic:
-    Add auth, rate limiting, logging here before reaching MCP.
+# =============================================================================
+# Lifespan — Session-Manager für die Lebensdauer des Servers
+# =============================================================================
+@contextlib.asynccontextmanager
+async def lifespan():
     """
-    if _mcp is None:
-        logger.error("MCP not initialized — call initialize() first.")
-        from quart import jsonify
-        return jsonify({"error": "MCP not initialized"}), 503
-
-    # --- Interceptor hooks (uncomment as needed) ---
-    # logger.debug(f"MCP SSE request: {request.method} {request.path}")
-    # await _check_auth(request)
-    # await _rate_limit(request)
-    # await _log_payload(request)
-
-    return await _mcp.handle_sse(request)
+    Runs the FastMCP session manager for the lifetime of the server.
+
+    WHY: FastMCP's streamable_http_app() starts its session manager in the
+    Starlette lifespan. Because app/app.py mounts it behind a plain ASGI
+    middleware (lifespan scope goes to Quart, not to the inner app), we have
+    to run it ourselves — otherwise every request fails with
+    'Task group is not initialized'.
+    Call AFTER get_asgi_app() (it creates the session manager).
+    """
+    if _mcp is not None and _transport == "streamable-http":
+        async with _mcp.session_manager.run():
+            yield
+    else:
+        yield
 
 
 # =============================================================================
@@ -276,92 +287,344 @@ def _register_system_tools(mcp) -> None:
             "active_search_providers": providers.list_active_search(),
             "active_tools":            tools.list_all(),
             "available_models":        models.list_all(),
+            "pricing_stats":           pricing.stats(),
         }
 
     logger.info("Tool registered: list_active_tools")
 
     @mcp.tool()
-    def health_check() -> Dict[str, str]:
+    async def health_check() -> Dict[str, Any]:
         """
-        Health check endpoint for HuggingFace Spaces and monitoring systems.
+        Health check: hub status + PostgreSQL awake-check (short ping, also wakes a
+        sleeping Neon), persist queue depth, active providers, integrations.
 
         Returns:
-            Dict with service status and active transport.
+            Dict — status "ok" | "degraded" (PostgreSQL configured but not answering).
         """
-        return {
-            "status":    "ok",
-            "service":   "Universal MCP Hub",
-            "transport": _transport,
-        }
+        result = await tools.health()
+        result["transport"] = _transport
+        return result
 
     logger.info("Tool registered: health_check")
 
     @mcp.tool()
-    def get_model_info(model_name: str) -> Dict[str, Any]:
+    async def get_model_info(model_name: str) -> Dict[str, Any]:
         """
         Get limits, costs, and capabilities for a specific model.
+        Costs are MERGED: .pyfun manual values win, auto-fetched values
+        (OpenRouter / LiteLLM) fill the gaps.
 
         Args:
             model_name: Model name as defined in .pyfun [MODELS] (e.g. 'claude-sonnet-4-6').
 
         Returns:
             Dict with context size, max output tokens, rate limits, costs, and capabilities.
-            Returns empty dict if model is not configured in .pyfun.
+            Returns pricing source info. Empty dict if model unknown.
         """
-        return models.get(model_name)
+        # .pyfun [MODELS] als Basis + Auto-Pricing füllt Lücken
+        merged = await pricing.get_pricing(model_name)
+        if not merged.get("provider") and not merged.get("cost_input_per_1k"):
+            return merged  # komplett unbekanntes Model
+        return merged
 
     logger.info("Tool registered: get_model_info")
 
 
 # =============================================================================
-# DB Tools — uncomment when db_sync.py is ready
+# Pricing Tools — auto-fetched model costs (OpenRouter + LiteLLM)
 # =============================================================================
-# def _register_db_tools(mcp) -> None:
-#     """
-#     Register internal SQLite query tool.
-#     Uses db_sync.py (app/* internal SQLite) — NOT postgresql.py (Guardian-only)!
-#
-#     SECURITY: Only SELECT queries are permitted.
-#     Enforced at application level in db_sync.query() — not just in docs.
-#     Tables accessible: hub_state, tool_cache  (app/* only)
-#     Tables blocked:    users, sessions         (Guardian-only, different owner)
-#
-#     To enable:
-#         1. Uncomment this function
-#         2. Uncomment _register_db_tools(_mcp) in initialize()
-#         3. Make sure db_sync.initialize() is called in app/app.py before mcp.initialize()
-#     """
-#     from . import db_sync
-#
-#     @mcp.tool()
-#     async def db_query(sql: str) -> list:
-#         """
-#         Execute a read-only SELECT query on the internal hub state database.
-#
-#         Only SELECT statements are permitted — all write operations are blocked
-#         at the db_sync layer (not just by convention).
-#
-#         Accessible tables:
-#             hub_state   — current hub runtime state (tool status, uptime, etc.)
-#             tool_cache  — cached tool results for repeated queries
-#
-#         NOT accessible (Guardian-only):
-#             users       — managed by fundaments/user_handler.py
-#             sessions    — managed by fundaments/user_handler.py
-#
-#         Args:
-#             sql: SQL SELECT statement. Example: "SELECT * FROM hub_state LIMIT 10"
-#
-#         Returns:
-#             List of result rows as dicts. Empty list if no results.
-#
-#         Raises:
-#             ValueError: If statement is not a SELECT query.
-#             RuntimeError: If db_sync is not initialized.
-#         """
-#         return await db_sync.query(sql)
-#
-#     logger.info("Tool registered: db_query (SQLite SELECT-only, app/* tables)")
+def _register_pricing_tools(mcp) -> None:
+    """
+    Register pricing tools.
+    Answers the question nobody wants to maintain by hand:
+    'Was kostet dieses Model?' — ohne [.MODELS] Kosten von Hand zu pflegen.
+    """
+
+    @mcp.tool()
+    async def get_model_pricing(model_name: str) -> Dict[str, Any]:
+        """
+        Get current pricing for a model — auto-fetched, no manual maintenance.
+
+        Merge order (highest priority first):
+            1. .pyfun [MODELS] manual values — your override always wins
+            2. OpenRouter public models API (all OR models, per-token USD)
+            3. LiteLLM community price list (Anthropic, Gemini, OpenAI, ...)
+
+        Args:
+            model_name: Model name (e.g. 'claude-opus-4-6', 'gemini-2.5-flash',
+                        'meta-llama/llama-3.3-70b-instruct').
+
+        Returns:
+            Dict with cost_input_per_1k, cost_output_per_1k (USD),
+            context_tokens, max_output_tokens, source, pricing_note.
+        """
+        return await pricing.get_pricing(model_name)
+
+    logger.info("Tool registered: get_model_pricing")
+
+    @mcp.tool()
+    async def refresh_pricing() -> Dict[str, Any]:
+        """
+        Force a pricing refresh from OpenRouter + LiteLLM.
+        Updates the db_sync cache (TTL-gated, default 24h).
+
+        Returns:
+            Dict with fetched_at, per-source model counts, and total cached models.
+        """
+        return await pricing.refresh()
+
+    logger.info("Tool registered: refresh_pricing")
+
+    @mcp.tool()
+    async def usage_stats(group_by: str = "model", days: int = 0) -> Dict[str, Any]:
+        """
+        What did my LLM calls cost? Aggregated from the usage_log table.
+
+        Args:
+            group_by: "model" | "provider" | "tool" | "day". Default: "model".
+            days:     Only the last N days (0 = all time).
+
+        Returns:
+            Dict with rows (calls, tokens_in, tokens_out, cost_usd, calls_unpriced per group)
+            and a total. cost_usd is an ESTIMATE from merged pricing; calls_unpriced counts
+            calls for which no price was known.
+        """
+        from . import db_sync
+        return await db_sync.usage_stats(group_by=group_by, days=days or None)
+
+    logger.info("Tool registered: usage_stats")
+
+    @mcp.tool()
+    async def openrouter_catalog(query: str = "", free_only: bool = True, limit: int = 40) -> Dict[str, Any]:
+        """
+        Real model IDs from the live OpenRouter catalog — to pick valid entries for .pyfun [MODELS]
+        (free models come and go; `stale_models` in health_check lists the ones that vanished).
+
+        Args:
+            query:     Substring filter, e.g. "llama", "qwen", "gemma".
+            free_only: Only ":free" models (default True).
+            limit:     Max rows (1-200).
+
+        Returns:
+            {in_catalog, matches, shown, models:[{id, context_tokens, cost_input_per_1k, cost_output_per_1k}]}
+        """
+        from . import pricing
+        return await pricing.catalog(query=query, free_only=free_only, limit=limit)
+
+    logger.info("Tool registered: openrouter_catalog")
+
+
+# =============================================================================
+# DB Tools — db_sync.py is ready, enabled
+# =============================================================================
+def _register_db_tools(mcp) -> None:
+    """
+    Register internal SQLite query tool.
+    Uses db_sync.py (app/* internal SQLite) — NOT postgresql.py (Guardian-only)!
+
+    SECURITY: Only a single SELECT is permitted.
+    Enforced in db_sync.query(): read-only connection, users/sessions/sqlite internals
+    rejected, max 1000 rows.
+    Tables accessible: hub_state, tool_cache, persist_queue, usage_log  (app/* only)
+    Tables blocked:    users, sessions         (Guardian-only, different owner)
+
+    Requirements (all met):
+        1. This function enabled
+        2. _register_db_tools(_mcp) called in initialize()
+        3. db_sync.initialize() runs in app/app.py BEFORE mcp.initialize()
+    """
+    from . import db_sync
+
+    @mcp.tool()
+    async def db_query(sql: str) -> list:
+        """
+        Execute a read-only SELECT query on the internal hub state database.
+
+        Only SELECT statements are permitted — all write operations are blocked
+        at the db_sync layer (not just by convention).
+
+        Accessible tables:
+            hub_state     — current hub runtime state (tool status, uptime, etc.)
+            tool_cache    — cached tool results for repeated queries
+            persist_queue — memory queue waiting for PostgreSQL
+            usage_log     — tokens + estimated cost per LLM call
+
+        NOT accessible (Guardian-only):
+            users       — managed by fundaments/user_handler.py
+            sessions    — managed by fundaments/user_handler.py
+
+        Args:
+            sql: SQL SELECT statement. Example: "SELECT * FROM hub_state LIMIT 10"
+
+        Returns:
+            List of result rows as dicts. Empty list if no results.
+
+        Raises:
+            ValueError: If statement is not a SELECT query.
+            RuntimeError: If db_sync is not initialized.
+        """
+        return await db_sync.query(sql)
+
+    logger.info("Tool registered: db_query (SQLite SELECT-only, app/* tables)")
+
+
+# =============================================================================
+# Persist Tools — Gedächtnis-Orchestrierung (SQLite-Queue → PostgreSQL)
+# =============================================================================
+def _register_skills_tools(mcp) -> None:
+    """show_skills / search_skills — only if active in .pyfun AND skill DBs were found."""
+    from . import skills_db
+    if not skills_db.is_ready():
+        return
+
+    if "show_skills" in tools.list_all():
+        @mcp.tool()
+        async def show_skills(scope: str = "all", tag: str = "") -> Any:
+            """
+            List available skills (name, description, tags, chunk count).
+
+            Args:
+                scope: "all" (default) | "user" | "agent". The core skill is never listed.
+                tag:   Optional tag filter.
+            """
+            return await tools.run("show_skills", scope=scope, tag=tag)
+
+        logger.info("Tool registered: show_skills")
+
+    if "search_skills" in tools.list_all():
+        @mcp.tool()
+        async def search_skills(query: str, top_k: int = 3, tag: str = "", scope: str = "user") -> Any:
+            """
+            Keyword search (BM25) over skills — returns the best matching chunks.
+
+            Args:
+                query: Search words.
+                top_k: 1-10 chunks. Default 3.
+                tag:   Optional tag filter.
+                scope: "user" (default) | "agent" | "all". The core skill is never searchable.
+            """
+            return await tools.run("search_skills", prompt=query, top_k=top_k, tag=tag, scope=scope)
+
+        logger.info("Tool registered: search_skills")
+
+
+def _register_integration_tools(mcp) -> None:
+    """
+    Optional integrations — registered ONLY if the tool is active in .pyfun AND the module is ready.
+      discord_post → hub posts into Discord (app/discord_api.py, [DISCORD])
+      gsc_query    → Search Console top queries/pages (app/gsc.py, [GSC])
+    """
+    if "discord_post" in tools.list_all():
+        from . import discord_api
+        if discord_api.is_ready():
+            @mcp.tool()
+            async def discord_post(message: str, channel_id: str = "") -> Dict[str, Any]:
+                """
+                Post a message to Discord (max 2000 chars).
+
+                Args:
+                    message:    The text to post.
+                    channel_id: Optional channel — only accepted if listed in DISCORD_ALLOWED_CHANNELS.
+                                Empty = default channel / webhook.
+
+                Returns:
+                    {"ok": bool, "error": str|None, "message_id": str|None}
+                """
+                return await tools.run("discord_post", prompt=message, channel_id=channel_id)
+
+            logger.info("Tool registered: discord_post")
+        else:
+            logger.info("discord_post active in .pyfun but Discord not ready — skipped.")
+
+    if "gsc_query" in tools.list_all():
+        from . import gsc
+        if gsc.is_ready():
+            @mcp.tool()
+            async def gsc_query(
+                property_url: str = "",
+                days_back: int = 30,
+                row_limit: int = 10,
+                dimension: str = "query",
+            ) -> Any:
+                """
+                Google Search Console: top queries (or pages) of a property, read-only.
+
+                Args:
+                    property_url: 'sc-domain:example.com' or 'https://example.com/'. Empty = default property.
+                    days_back:    1-365 days (data lags 2-3 days). Default 30.
+                    row_limit:    1-100 rows. Default 10.
+                    dimension:    query | page | country | device | date. Default: query.
+
+                Returns:
+                    List of {keyword|page|..., clicks, impressions, ctr (%), position}.
+                """
+                return await tools.run(
+                    "gsc_query", property_url=property_url, days_back=days_back,
+                    row_limit=row_limit, dimension=dimension,
+                )
+
+            logger.info("Tool registered: gsc_query")
+        else:
+            logger.info("gsc_query active in .pyfun but GSC not ready — skipped.")
+
+
+def _register_persist_tools(mcp) -> None:
+    """
+    Register memory-orchestration tools.
+
+    persist_result works WITHOUT PostgreSQL: entries queue restart-safe in
+    the SQLite persist_queue (db_sync) and flush automatically once the
+    Guardian-injected PostgreSQL bridge is active. No key = queued, not crash.
+    """
+    if "persist_result" not in tools.list_all():
+        logger.info("persist_result not active in .pyfun — skipped.")
+        return
+
+    @mcp.tool()
+    async def persist_result(
+        prompt: str = None,
+        source: str = None,
+        model: str = None,
+        score: float = None,
+    ) -> Dict[str, Any]:
+        """
+        Persist a result to long-term memory (PostgreSQL).
+
+        Restart-safe: without DATABASE_URL the entry queues in SQLite and
+        flushes automatically once PostgreSQL is available. Never crashes.
+
+        Args:
+            prompt: The text/result to persist (or hub_state key via .pyfun state_read_key).
+            source: Which tool/component produced this entry (optional).
+            model:  Which model produced this entry (optional).
+            score:  Optional quality score — reserved slot, set by your own filter.
+
+        Returns:
+            Dict with status ('persisted' | 'queued'), target_table, queue_depth.
+        """
+        return await tools.run(
+            tool_name="persist_result",
+            prompt=prompt,
+            source=source,
+            model=model,
+            score=score,
+        )
+
+    logger.info("Tool registered: persist_result (queue-safe memory orchestration)")
+
+    @mcp.tool()
+    async def persist_status() -> Dict[str, Any]:
+        """
+        Show memory orchestration status: queue depth, oldest entry,
+        failed attempts, and whether the PostgreSQL bridge is active.
+
+        Returns:
+            Dict with queue stats — observability for the memory pipeline.
+        """
+        from . import db_sync
+        return await db_sync.persist_queue_stats()
+
+    logger.info("Tool registered: persist_status")
 
 
 # =============================================================================

app/models.py

@@ -39,8 +39,10 @@ def initialize() -> None:
 
 
 def get(model_name: str) -> dict:
-    """Get model config by name."""
-    return _registry.get(model_name, {})
+    """Get model config by name. Falls back to raw .pyfun if not initialized yet."""
+    if _registry:
+        return _registry.get(model_name, {})
+    return config.get_models().get(model_name, {})
 
 
 def get_limit(model_name: str, key: str, default=None):

app/pricing.py

@@ -0,0 +1,526 @@
+# =============================================================================
+# app/pricing.py
+# Auto Model Pricing — weil niemand Lust hat, Kosten von Hand zu pflegen.
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# ARCHITECTURE NOTE:
+#   This file lives exclusively in app/ and is ONLY started by app/app.py.
+#   NO direct access to fundaments/*, .env, or Guardian (main.py).
+#   All config comes from app/.pyfun [PRICING] via app/config.py.
+#
+# WHY THIS EXISTS:
+#   Not every provider has a pricing API (Anthropic & Google: none).
+#   Manually maintaining cost_input_per_1k in [MODELS] sucks. Solution:
+#   two free public sources cover almost everything, .pyfun stays the override.
+#
+# SOURCES (priority: .pyfun manual > OpenRouter > LiteLLM):
+#   1. .pyfun [MODELS]           → your values ALWAYS win (manual override)
+#   2. OpenRouter /api/v1/models → public, no key. Pricing per token for all
+#                                  OR models + context_length + max_completion_tokens
+#   3. LiteLLM community JSON    → github.com/BerriAI/litellm main branch.
+#                                  input_cost_per_token / output_cost_per_token
+#                                  for Anthropic, Gemini, OpenAI, Mistral, ...
+#
+# PRINCIPLE (same as everything here):
+#   No network = no crash. No match = costs stay as configured.
+#   Server always starts — pricing refresh runs in the BACKGROUND.
+#
+# CACHING:
+#   Fetched data lands in db_sync hub_state ("pricing.cache") with TTL
+#   from .pyfun (default 24h). Restart within TTL = no external call.
+#
+# MCP TOOLS (registered in mcp.py):
+#   get_model_pricing(model_name)  → merged cost info for one model
+#   refresh_pricing()              → force refresh, returns source counts
+# =============================================================================
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+import httpx
+
+from . import config
+from . import db_sync
+
+logger = logging.getLogger("pricing")
+
+# =============================================================================
+# Internal State
+# =============================================================================
+_cache: Dict[str, Dict[str, Any]] = {}   # normalized_name → {cost_in_1k, cost_out_1k, context, max_out, source}
+_meta: Dict[str, Any] = {}               # {"fetched_at": iso, "sources": {...}, "model_count": int}
+_task: Optional[asyncio.Task] = None     # background refresh task
+_initialized: bool = False
+
+# Loose index: alnum-only keys for dot/dash-insensitive matching.
+# Why: OpenRouter writes 'claude-opus-4.6', LiteLLM 'claude-opus-4-6',
+# your .pyfun 'claude-opus-4-6'. All should find each other.
+_loose_index: Dict[str, str] = {}        # loose_key → normalized cache key
+_loose_dirty: bool = True
+
+_HUB_STATE_KEY = "pricing.cache"
+
+# Known vendor prefixes used by OpenRouter / LiteLLM IDs
+# ("anthropic/claude-...", "gemini/gemini-...", "meta-llama/llama-...", ...)
+_VENDOR_PREFIXES = (
+    "anthropic/", "google/", "openai/", "meta-llama/", "mistralai/", "mistral/",
+    "qwen/", "nvidia/", "microsoft/", "deepseek/", "x-ai/", "xai/", "perplexity/",
+    "cohere/", "gryphe/", "thedrummer/", "undi95/", "cognitivecomputations/",
+    "gemini/", "groq/", "together_ai/", "together/", "openrouter/", "fireworks_ai/",
+    "azure/", "vertex_ai/", "bedrock/", "cloudflare/", "voyage/", "sambanova/",
+    "ai21/", "huggingface/", "ollama/", "ollama_chat/",
+)
+
+
+# =============================================================================
+# Normalization — model IDs differ wildly between sources
+# =============================================================================
+def _normalize(name: str) -> str:
+    """
+    Normalize a model name for matching across sources.
+    'anthropic/claude-haiku-4.5' → 'claude-haiku-4.5'
+    'Claude-Haiku-4.5'           → 'claude-haiku-4.5'
+    Dots vs dashes are kept — providers are inconsistent there by design.
+    """
+    n = (name or "").strip().lower()
+    for prefix in _VENDOR_PREFIXES:
+        if n.startswith(prefix):
+            n = n[len(prefix):]
+            break
+    return n
+
+
+def _safe_int(value: Any) -> Optional[int]:
+    """int() that returns None instead of raising (LiteLLM ships doc samples
+    like sample_spec.max_input_tokens = 'max input tokens, if the provider specifies it')."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _per_token_to_per_1k(cost: Any) -> Optional[float]:
+    """'0.0000015' per token → 0.0015 per 1k tokens. Returns None on garbage."""
+    try:
+        val = float(cost)
+    except (TypeError, ValueError):
+        return None
+    if val < 0:  # negative = OpenRouter's "we pay you" marker → treat as 0
+        val = 0.0
+    return round(val * 1000, 6)
+
+
+def _loose(name: str) -> str:
+    """Strip everything except a-z0-9 — kills dot/dash/underscore differences."""
+    return "".join(ch for ch in name if ch.isalnum())
+
+
+def _rebuild_loose_index() -> None:
+    """Rebuild the alnum-only lookup index after a cache change."""
+    global _loose_index, _loose_dirty
+    _loose_index = {_loose(k): k for k in _cache}
+    _loose_dirty = False
+
+
+def _lookup(model_name: str) -> Optional[Dict[str, Any]]:
+    """
+    Cache lookup with graceful fallback:
+        1. exact normalized match ('claude-opus-4-6')
+        2. loose alnum match ('claude-opus-4.6' ≈ 'claude-opus-4-6')
+    """
+    norm = _normalize(model_name)
+    hit = _cache.get(norm)
+    if hit:
+        return hit
+    if _loose_dirty:
+        _rebuild_loose_index()
+    loose_key = _loose_index.get(_loose(norm))
+    if loose_key:
+        return _cache.get(loose_key)
+    return None
+
+
+# =============================================================================
+# Source Fetchers — each returns {normalized_name: entry}
+# =============================================================================
+async def _fetch_openrouter(url: str):
+    """
+    OpenRouter public models endpoint — no key required.
+    https://openrouter.ai/api/v1/models → data[].{id, pricing{prompt,completion}, context_length}
+
+    Returns (entries, raw_ids): raw_ids = every real OpenRouter model ID (lowercase) —
+    used by check_models() to spot stale/removed models in .pyfun [MODELS].
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    raw_ids = []
+    async with httpx.AsyncClient() as client:
+        r = await client.get(url, timeout=30)
+        r.raise_for_status()
+        payload = r.json()
+
+    for m in payload.get("data", []):
+        model_id = m.get("id", "")
+        if not model_id:
+            continue
+        raw_ids.append(model_id.lower())
+        pricing = m.get("pricing", {}) or {}
+        entry: Dict[str, Any] = {"source": "openrouter"}
+
+        cost_in  = _per_token_to_per_1k(pricing.get("prompt"))
+        cost_out = _per_token_to_per_1k(pricing.get("completion"))
+        if cost_in is not None:
+            entry["cost_input_per_1k"] = cost_in
+        if cost_out is not None:
+            entry["cost_output_per_1k"] = cost_out
+        if m.get("context_length"):
+            ctx = _safe_int(m["context_length"])
+            if ctx:
+                entry["context_tokens"] = ctx
+
+        # max_completion_tokens is nested under top_provider in OR payloads
+        max_out = _safe_int((m.get("top_provider") or {}).get("max_completion_tokens"))
+        if max_out:
+            entry["max_output_tokens"] = max_out
+
+        out[_normalize(model_id)] = entry
+    return out, raw_ids
+
+
+async def _fetch_litellm(url: str) -> Dict[str, Dict[str, Any]]:
+    """
+    LiteLLM community price list — no key required.
+    github.com/BerriAI/litellm → model_prices_and_context_window.json
+    Keys like 'claude-sonnet-4-5', 'gemini/gemini-2.5-flash', 'gpt-4o'.
+    """
+    out: Dict[str, Dict[str, Any]] = {}
+    async with httpx.AsyncClient() as client:
+        r = await client.get(url, timeout=30)
+        r.raise_for_status()
+        payload = r.json()
+
+    for model_id, info in payload.items():
+        if not isinstance(info, dict):
+            continue  # skip metadata keys like "additional_vendor_names"
+        entry: Dict[str, Any] = {"source": "litellm"}
+
+        cost_in  = _per_token_to_per_1k(info.get("input_cost_per_token"))
+        cost_out = _per_token_to_per_1k(info.get("output_cost_per_token"))
+        if cost_in is not None:
+            entry["cost_input_per_1k"] = cost_in
+        if cost_out is not None:
+            entry["cost_output_per_1k"] = cost_out
+        if info.get("max_input_tokens"):
+            ctx = _safe_int(info["max_input_tokens"])
+            if ctx:
+                entry["context_tokens"] = ctx
+        if info.get("max_output_tokens"):
+            max_out = _safe_int(info["max_output_tokens"])
+            if max_out:
+                entry["max_output_tokens"] = max_out
+
+        out[_normalize(model_id)] = entry
+    return out
+
+
+# =============================================================================
+# Cache — db_sync hub_state, TTL-gated
+# =============================================================================
+def _cache_is_fresh() -> bool:
+    if not _cache or not _meta.get("fetched_at"):
+        return False
+    from datetime import datetime, timezone
+    try:
+        fetched = datetime.fromisoformat(_meta["fetched_at"])
+    except (ValueError, TypeError):
+        return False
+    ttl_hours = float(config.get_pricing().get("PRICING_TTL_HOURS", "24"))
+    age = datetime.now(timezone.utc) - fetched
+    return age.total_seconds() < ttl_hours * 3600
+
+
+async def _load_cache_from_db() -> None:
+    """Read pricing cache from db_sync — never raises."""
+    global _cache, _meta, _loose_dirty
+    try:
+        stored = await db_sync.read(_HUB_STATE_KEY, default=None)
+        if isinstance(stored, dict) and stored.get("models"):
+            _cache = stored["models"]
+            _meta = stored.get("meta", {})
+            _loose_dirty = True
+            logger.info(
+                f"Pricing cache loaded from db_sync: {len(_cache)} models "
+                f"(fetched_at: {_meta.get('fetched_at', 'unknown')})"
+            )
+    except Exception as e:
+        logger.warning(f"Pricing cache load failed (continuing without): {type(e).__name__}")
+
+
+async def _save_cache_to_db() -> None:
+    """Write pricing cache to db_sync — never raises."""
+    try:
+        await db_sync.write(_HUB_STATE_KEY, {"models": _cache, "meta": _meta})
+    except Exception as e:
+        logger.warning(f"Pricing cache save failed: {type(e).__name__}")
+
+
+# =============================================================================
+# Refresh — fetch sources, merge, cache
+# =============================================================================
+async def refresh() -> Dict[str, Any]:
+    """
+    Fetch all pricing sources, rebuild the auto-pricing cache.
+    Never raises — a failing source is just skipped (no fetch = no crash).
+    """
+    global _cache, _meta, _loose_dirty
+    from datetime import datetime, timezone
+
+    cfg       = config.get_pricing()
+    or_url    = cfg.get("OPENROUTER_MODELS_URL", "https://openrouter.ai/api/v1/models")
+    llm_url   = cfg.get(
+        "LITELLM_PRICES_URL",
+        "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json",
+    )
+
+    merged: Dict[str, Dict[str, Any]] = {}
+    sources: Dict[str, int] = {}
+    or_ids: list = []
+
+    # --- Source 1: OpenRouter ---
+    try:
+        or_models, or_ids = await _fetch_openrouter(or_url)
+        merged.update(or_models)
+        sources["openrouter"] = len(or_models)
+        logger.info(f"Pricing source OpenRouter: {len(or_models)} models.")
+    except Exception as e:
+        sources["openrouter"] = 0
+        logger.warning(f"Pricing source OpenRouter failed: {type(e).__name__} — skipped.")
+
+    # --- Source 2: LiteLLM (fills gaps — never overwrites OpenRouter) ---
+    try:
+        llm_models = await _fetch_litellm(llm_url)
+        for name, entry in llm_models.items():
+            if name not in merged:
+                merged[name] = entry
+        sources["litellm"] = len(llm_models)
+        logger.info(f"Pricing source LiteLLM: {len(llm_models)} models.")
+    except Exception as e:
+        sources["litellm"] = 0
+        logger.warning(f"Pricing source LiteLLM failed: {type(e).__name__} — skipped.")
+
+    if merged:
+        _cache = merged
+        _meta = {
+            "fetched_at": datetime.now(timezone.utc).isoformat(),
+            "sources": sources,
+            "model_count": len(merged),
+            # keep the last known OpenRouter ID list if this fetch failed
+            "openrouter_ids": or_ids or _meta.get("openrouter_ids", []),
+        }
+        _loose_dirty = True
+        await _save_cache_to_db()
+
+    stale = check_models()
+    if stale:
+        logger.warning(f"Models in .pyfun not found in OpenRouter catalog (stale/removed?): {stale}")
+
+    return {
+        "fetched_at": _meta.get("fetched_at"),
+        "sources": sources,
+        "models_cached": len(_cache),
+        "stale_models": stale,
+    }
+
+
+# =============================================================================
+# Initialization — called by app/app.py, NON-BLOCKING
+# =============================================================================
+async def initialize() -> None:
+    """
+    Prepare auto-pricing. Loads the db_sync cache if fresh; otherwise kicks
+    off a BACKGROUND refresh (asyncio.create_task) — the server never waits
+    for external pricing APIs. No network = no crash.
+    """
+    global _initialized, _task
+    if _initialized:
+        return
+
+    cfg = config.get_pricing()
+    enabled = cfg.get("PRICING_ENABLED", "true").lower() == "true"
+
+    if not enabled:
+        logger.info("Auto-pricing disabled in .pyfun [PRICING] — .pyfun [MODELS] values only.")
+        _initialized = True
+        return
+
+    await _load_cache_from_db()
+
+    if _cache_is_fresh():
+        logger.info("Auto-pricing cache fresh — no external fetch needed.")
+    else:
+        logger.info("Auto-pricing cache stale/empty — background refresh started.")
+        _task = asyncio.create_task(_background_refresh())
+
+    _initialized = True
+
+
+async def _background_refresh() -> None:
+    """Runs refresh() and swallows everything — background task must never crash the app."""
+    try:
+        await refresh()
+    except Exception as e:
+        logger.warning(f"Pricing background refresh failed (non-fatal): {type(e).__name__}")
+
+
+# =============================================================================
+# Public API — merged view: .pyfun manual values WIN over auto-fetched
+# =============================================================================
+async def get_pricing(model_name: str) -> Dict[str, Any]:
+    """
+    Returns merged pricing info for one model.
+
+    Merge order (highest priority first):
+        1. .pyfun [MODELS.<model>]   → your manual values always win
+        2. auto-fetched cache        → OpenRouter / LiteLLM
+        3. nothing                   → costs omitted, source: "unknown"
+
+    Returns dict with: model, provider (if known from .pyfun),
+    cost_input_per_1k, cost_output_per_1k (USD), context_tokens,
+    max_output_tokens, source ("pyfun" | "openrouter" | "litellm" | "unknown"),
+    pricing_note.
+    """
+    from . import models as models_mod
+
+    result: Dict[str, Any] = {"model": model_name}
+    notes = []
+
+    # --- Layer 1: .pyfun manual config (models.py reads [MODELS]) ---
+    manual = models_mod.get(model_name)
+    if manual:
+        result["provider"] = manual.get("provider", "")
+        for key in ("cost_input_per_1k", "cost_output_per_1k",
+                    "context_tokens", "max_output_tokens",
+                    "requests_per_min", "requests_per_day", "capabilities"):
+            if manual.get(key):
+                value = manual[key]
+                if key.startswith("cost_"):
+                    # .pyfun-Werte sind Strings ("0.015") — Auto-Werte sind float.
+                    # Normalisieren, damit die API immer Zahlen liefert.
+                    try:
+                        value = round(float(value), 6)
+                    except (TypeError, ValueError):
+                        pass
+                result[key] = value
+        if manual.get("cost_input_per_1k") or manual.get("cost_output_per_1k"):
+            result["source"] = "pyfun"
+            notes.append(".pyfun manual values (override)")
+        else:
+            notes.append(".pyfun entry has no costs — auto values used")
+
+    # --- Layer 2: auto-fetched cache fills the gaps ---
+    auto = _lookup(model_name)
+    if auto:
+        for key in ("cost_input_per_1k", "cost_output_per_1k",
+                    "context_tokens", "max_output_tokens"):
+            if key not in result and auto.get(key) is not None:
+                result[key] = auto[key]
+        if "source" not in result:
+            result["source"] = auto.get("source", "auto")
+            notes.append(f"auto-fetched from {auto.get('source', 'unknown')}")
+    elif "source" not in result:
+        result["source"] = "unknown"
+        notes.append("no auto source matched this model name")
+
+    # --- Stale hint ---
+    if _cache and not _cache_is_fresh():
+        notes.append("cache stale — refresh_pricing() to update")
+
+    result["pricing_note"] = "; ".join(notes) if notes else "ok"
+    return result
+
+
+async def catalog(query: str = "", free_only: bool = False, limit: int = 50) -> Dict[str, Any]:
+    """
+    Real model IDs of the live OpenRouter catalog (for picking valid [MODELS] entries).
+    Fetches the catalog once if it is not loaded yet. Read-only, no key needed.
+    """
+    if not _meta.get("openrouter_ids"):
+        await refresh()
+    ids = _meta.get("openrouter_ids") or []
+    q = (query or "").strip().lower()
+    hits = sorted(i for i in ids if (not free_only or i.endswith(":free")) and (not q or q in i))
+    limit = max(1, min(int(limit or 50), 200))
+    rows = []
+    for i in hits[:limit]:
+        info = _lookup(i) or {}
+        rows.append({"id": i, "context_tokens": info.get("context_tokens"),
+                     "cost_input_per_1k": info.get("cost_input_per_1k"),
+                     "cost_output_per_1k": info.get("cost_output_per_1k")})
+    return {"in_catalog": len(ids), "matches": len(hits), "shown": len(rows), "models": rows}
+
+
+def check_models() -> list:
+    """
+    .pyfun [MODELS] entries with provider "openrouter" whose ID is NOT in the live
+    OpenRouter catalog (free models come and go). Empty list if the catalog is unknown.
+    """
+    ids = set(_meta.get("openrouter_ids") or [])
+    if not ids:
+        return []
+    return sorted(
+        name for name, cfg in config.get_models().items()
+        if cfg.get("provider") == "openrouter" and name.lower() not in ids
+    )
+
+
+def max_output_for(model_name: str) -> Optional[int]:
+    """
+    Max output tokens for a model (sync, for clamping): manual .pyfun value wins,
+    then auto-fetched. None if unknown → no clamp.
+    """
+    from . import models as models_mod
+    manual = _safe_int((models_mod.get(model_name) or {}).get("max_output_tokens"))
+    if manual:
+        return manual
+    auto = _lookup(model_name) if _cache else None
+    return _safe_int(auto.get("max_output_tokens")) if auto else None
+
+
+async def cost_for(model_name: str, tokens_in: Optional[int], tokens_out: Optional[int]) -> Optional[float]:
+    """
+    Estimated USD cost of one call from merged pricing (manual > auto).
+    None if no price is known. Anthropic cache read/write surcharges are not modeled.
+    """
+    info = await get_pricing(model_name)
+    c_in, c_out = info.get("cost_input_per_1k"), info.get("cost_output_per_1k")
+    if c_in is None and c_out is None:
+        return None
+    try:
+        return round(((tokens_in or 0) / 1000) * float(c_in or 0)
+                     + ((tokens_out or 0) / 1000) * float(c_out or 0), 8)
+    except (TypeError, ValueError):
+        return None
+
+
+def is_ready() -> bool:
+    """True if pricing cache holds at least one model."""
+    return bool(_cache)
+
+
+def stats() -> Dict[str, Any]:
+    """Cache stats for list_active_tools / debugging."""
+    return {
+        "models_cached": len(_cache),
+        "fetched_at": _meta.get("fetched_at"),
+        "sources": _meta.get("sources", {}),
+        "fresh": _cache_is_fresh(),
+        "stale_models": check_models(),
+    }
+
+
+# =============================================================================
+# Direct execution guard
+# =============================================================================
+if __name__ == "__main__":
+    print("WARNING: Run via main.py → app.py, not directly.")

app/providers.py

@@ -1,6 +1,6 @@
 # =============================================================================
 # app/providers.py
-# 09.03.2026 | updated 23.03.2026
+# 09.03.2026 | updated 23.03.2026 | reworked 10.11.2026
 # LLM + Search Provider Registry + Fallback Chain
 # Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
 # Copyright 2026 - Volkan Kücükbudak
@@ -15,12 +15,33 @@
 # PROVIDER PRINCIPLE:
 #   No key = no provider = no tool = no crash.
 #   Server always starts, just with fewer providers.
-#   Adding a new provider = update .pyfun + add class here. Never touch mcp.py!
+#
+# HOW TO ADD A NEW LLM PROVIDER:
+#   OpenAI-compatible API (Mistral, OpenAI, xAI, Groq, Together, DeepSeek, ...):
+#       → ONLY a [LLM_PROVIDER.xyz] block in app/.pyfun with type = "openai_compat"
+#         + the key in .env. NO code needed. See examples in .pyfun.
+#   Different API format (like Anthropic / Gemini):
+#       1. Add a class below (subclass BaseProvider, implement complete())
+#       2. Register it in _TYPE_CLASSES
+#       3. Add the [LLM_PROVIDER.xyz] block in .pyfun with type = "<your type>"
 #
 # FALLBACK CHAIN:
 #   Defined in .pyfun per provider via fallback_to field.
 #   anthropic → fails → gemini → fails → openrouter → fails → RuntimeError
 #   Visited set prevents infinite loops.
+#   A model chosen explicitly applies to the FIRST provider only — every
+#   fallback provider uses its own default_model (model IDs are provider-specific).
+#
+# LIMITS (from .pyfun [HUB_LIMITS]):
+#   MAX_PARALLEL_REQUESTS → semaphore around every provider call
+#   RETRY_COUNT / RETRY_DELAY_SEC → attempts per provider on 429/5xx/connect errors
+#                                   (timeouts are NOT retried → straight to fallback)
+#   MAX_TOKENS_CAP → hard ceiling for max_tokens per call (0 = off)
+#   Per-model max_output_tokens (manual or auto from pricing) clamps further.
+#
+# USAGE / COST:
+#   complete() returns (text, usage). llm_complete() logs usage + estimated cost
+#   into db_sync (usage_log) after every successful call. Never breaks a call.
 #
 # SECURITY NOTE:
 #   API keys are NEVER logged or included in exception messages.
@@ -28,25 +49,9 @@
 #   and safe_url (query params stripped) are ever exposed in logs.
 #
 # CACHING NOTE:
-#   Anthropic → prompt_caching (cache_control: ephemeral)
-#     Requires anthropic-beta: prompt-caching-2024-07-31 header.
-#     Caches system prompt + long user prompts (>1024 tokens estimated).
-#     Saves up to 90% input token costs on repeated context.
+#   Anthropic → prompt_caching (cache_control: ephemeral) for long system/user prompts.
 #     Enable per provider in .pyfun: supports_cache = "true"
-#
-#   Gemini → Implicit caching (automatic, no extra API call needed)
-#     Google automatically caches repeated prompt prefixes server-side.
-#     No code change needed — Gemini handles it transparently.
-#     Explicit Context Caching API exists but requires separate cache management
-#     and is only worth it for very large static contexts (32k+ tokens).
-#     Enable per provider in .pyfun: supports_cache = "true"
-#     (currently used as log hint only for Gemini — implicit cache is always on)
-#
-# HOW TO ADD A NEW LLM PROVIDER — 3 steps, nothing else to touch:
-#   1. Add class below (copy a dummy, implement complete())
-#   2. Register name → class in _PROVIDER_CLASSES dict
-#   3. Add [LLM_PROVIDER.yourprovider] block in app/.pyfun
-#      → env_key, base_url, default_model, fallback_to
+#   Gemini → implicit caching (automatic, server-side). supports_cache = log hint only.
 #
 # DEPENDENCY CHAIN (app/* only, no fundaments!):
 #   config.py    → parses app/.pyfun — single source of truth
@@ -56,14 +61,92 @@
 # =============================================================================
 
 import os
+import re
+import time
+import asyncio
 import logging
 import httpx
+from html.parser import HTMLParser
+from urllib.parse import urlparse, parse_qs
+from typing import Optional, Tuple, Dict, Any
 
 from . import config
+from . import models as models_mod
+from . import pricing
+from . import db_sync
+
 logging.getLogger("httpx").setLevel(logging.WARNING)
 logger = logging.getLogger("providers")
 
 
+# =============================================================================
+# SECTION 0 — Errors, Limits, Retry
+# =============================================================================
+
+class ProviderError(RuntimeError):
+    """Sanitized provider error. RuntimeError subclass → app.py maps it to 502."""
+    def __init__(self, message: str, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+
+_TRANSIENT_STATUS = {408, 425, 429, 500, 502, 503, 504, 529}
+
+
+def _limit(key: str, default, cast=int):
+    """Read one value from .pyfun [HUB_LIMITS] with safe fallback."""
+    try:
+        return cast(config.get_limits().get(key, default))
+    except (TypeError, ValueError):
+        return cast(default)
+
+
+_sem: Optional[asyncio.Semaphore] = None
+
+
+def _get_sem() -> asyncio.Semaphore:
+    """One global semaphore (MAX_PARALLEL_REQUESTS) — created lazily inside the loop."""
+    global _sem
+    if _sem is None:
+        _sem = asyncio.Semaphore(max(1, _limit("MAX_PARALLEL_REQUESTS", 5)))
+    return _sem
+
+
+def _is_transient(e: Exception) -> bool:
+    """429/5xx and connect errors are worth a retry. Timeouts are NOT (60s x N = forever)."""
+    if isinstance(e, ProviderError):
+        return e.status in _TRANSIENT_STATUS
+    return isinstance(e, httpx.ConnectError)
+
+
+async def _with_retry(name: str, call):
+    """
+    Run `call()` (async callable) under the global semaphore.
+    Attempts = RETRY_COUNT (incl. the first), flat RETRY_DELAY_SEC between them.
+    """
+    attempts = max(1, _limit("RETRY_COUNT", 3))
+    delay    = max(0.0, _limit("RETRY_DELAY_SEC", 2, float))
+    for i in range(1, attempts + 1):
+        try:
+            async with _get_sem():
+                return await call()
+        except Exception as e:
+            if i >= attempts or not _is_transient(e):
+                raise
+            logger.info(f"'{name}' transient error ({type(e).__name__}) — retry {i}/{attempts - 1} in {delay}s")
+            await asyncio.sleep(delay)
+
+
+def _usage(tokens_in: Any, tokens_out: Any) -> Dict[str, Optional[int]]:
+    """Normalize token counts to int|None."""
+    def _i(v):
+        try:
+            return int(v)
+        except (TypeError, ValueError):
+            return None
+    return {"input": _i(tokens_in), "output": _i(tokens_out)}
+
+
 # =============================================================================
 # SECTION 1 — Base Provider
 # Shared HTTP logic — implemented ONCE, reused by all providers.
@@ -73,9 +156,11 @@ class BaseProvider:
     """
     Base class for all LLM providers.
     Subclasses only implement complete() — HTTP logic lives here.
+    complete() returns (text, usage) with usage = {"input": int|None, "output": int|None}.
     """
     def __init__(self, name: str, cfg: dict):
         self.name          = name
+        self.cfg           = cfg
         self.key           = os.getenv(cfg.get("env_key", ""))
         self.base_url      = cfg.get("base_url", "")
         self.fallback      = cfg.get("fallback_to", "")
@@ -89,14 +174,15 @@ class BaseProvider:
             else "***"
         )
 
-    async def complete(self, prompt: str, model: str, max_tokens: int) -> str:
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024,
+                       system: str = None) -> Tuple[str, Dict[str, Optional[int]]]:
         """Override in each provider subclass."""
         raise NotImplementedError
 
     async def _post(self, url: str, headers: dict, payload: dict) -> dict:
         """
         Shared HTTP POST — used by all providers.
-        Raises RuntimeError with sanitized message on non-2xx responses.
+        Raises ProviderError with sanitized message on non-2xx responses.
         API keys are never included in raised exceptions or log output.
         """
         safe_url = url.split("?")[0]  # strip query params (may contain API keys)
@@ -112,8 +198,9 @@ class BaseProvider:
                 r.raise_for_status()
             except httpx.HTTPStatusError as e:
                 # Sanitize: only status code + safe_url, never headers or body
-                raise RuntimeError(
-                    f"HTTP {e.response.status_code} from {safe_url}"
+                raise ProviderError(
+                    f"HTTP {e.response.status_code} from {safe_url}",
+                    e.response.status_code,
                 ) from None
             return r.json()
 
@@ -123,40 +210,74 @@ class BaseProvider:
 # Only the API-specific parsing logic differs per provider.
 # =============================================================================
 
-# --- SmolLM2 (Custom Assistant Space) ----------------------------------------
-class SmolLMProvider(BaseProvider):
+# --- OpenAI-compatible (GENERIC — no code needed for new providers) -----------
+class OpenAICompatProvider(BaseProvider):
     """
-    SmolLM2 Custom Assistant Space — OpenAI-compatible, ADI routing included.
-    Free tier on HF Spaces (CPU). Falls back to next provider on 503.
-    Response includes extra 'adi' field with score + decision (ignored by hub).
-    Deploy: https://github.com/VolkanSah/Multi-LLM-API-Gateway (smollm-space/)
+    Generic OpenAI-compatible /chat/completions provider.
+    Covers smollm, openrouter, huggingface, mistral, openai, xai, groq, ...
+    Everything provider-specific lives in the .pyfun block:
 
-    .pyfun block:
-        [LLM_PROVIDER.smollm]
+        [LLM_PROVIDER.mistral]
         active        = "true"
-        base_url      = "https://codey-lab-SmolLM2-customs.hf.space/v1"
-        env_key       = "SMOLLM_API_KEY"
-        default_model = "smollm2-360m"
-        models        = "smollm2-360m, codey-lab/model.universal-mcp-hub"
-        fallback_to   = "anthropic"
-        [LLM_PROVIDER.smollm_END]
+        type          = "openai_compat"
+        base_url      = "https://api.mistral.ai/v1"
+        env_key       = "MISTRAL_API_KEY"
+        default_model = "mistral-small-latest"
+        fallback_to   = ""
+        # optional:
+        # auth_header = "Authorization"   (default)
+        # auth_scheme = "Bearer"          (default; "" = send the raw key)
+        # chat_path   = "/chat/completions" (default)
+        # header.X-Foo = "{key}"          extra header; {key} = API key,
+        #                                 {env:NAME|fallback} = ENV value
+        [LLM_PROVIDER.mistral_END]
     """
+    _PLACEHOLDER = re.compile(r"\{(key|env:([A-Za-z0-9_]+)(?:\|([^}]*))?)\}")
+
+    def __init__(self, name: str, cfg: dict):
+        super().__init__(name, cfg)
+        self.auth_header = cfg.get("auth_header", "Authorization")
+        self.auth_scheme = cfg.get("auth_scheme", "Bearer")
+        self.chat_path   = cfg.get("chat_path", "/chat/completions")
+
+    def _fill(self, value: str) -> str:
+        def sub(m):
+            if m.group(1) == "key":
+                return self.key or ""
+            return os.getenv(m.group(2)) or (m.group(3) or "")
+        return self._PLACEHOLDER.sub(sub, value)
+
+    def _headers(self) -> dict:
+        headers = {
+            self.auth_header: f"{self.auth_scheme} {self.key}".strip(),
+            "content-type":   "application/json",
+        }
+        for k, v in self.cfg.items():
+            if k.startswith("header."):
+                headers[k[len("header."):]] = self._fill(v)
+        return headers
+
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024,
+                       system: str = None):
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
 
-    async def complete(self, prompt: str, model: str = None, max_tokens: int = 150) -> str:
         data = await self._post(
-            f"{self.base_url}/chat/completions",
-            headers={
-                "Authorization": f"Bearer {self.key}",
-                "X-IP-Token":     self.key,
-                "content-type":  "application/json",
-            },
+            f"{self.base_url}{self.chat_path}",
+            headers=self._headers(),
             payload={
                 "model":      model or self.model,
                 "max_tokens": max_tokens,
-                "messages":   [{"role": "user", "content": prompt}],
+                "messages":   messages,
             },
         )
-        return data["choices"][0]["message"]["content"]
+        text = data["choices"][0]["message"]["content"]
+        if text is None:
+            raise ProviderError("empty content in response")
+        u = data.get("usage") or {}
+        return text, _usage(u.get("prompt_tokens"), u.get("completion_tokens"))
 
 
 # --- Anthropic ----------------------------------------------------------------
@@ -166,20 +287,22 @@ class AnthropicProvider(BaseProvider):
 
     Prompt Caching (supports_cache = "true" in .pyfun):
         Uses cache_control: ephemeral on system prompt and long user prompts.
-        Requires anthropic-beta: prompt-caching-2024-07-31 header.
         Cache TTL: 5 minutes, extended on each cache hit.
         Min tokens to cache: ~1024 (Anthropic requirement).
         Cost: cache write ~25% more, cache read ~90% less than normal input.
 
+    Usage: input = input + cache_creation + cache_read tokens (upper bound for cost).
+
     .pyfun block:
         [LLM_PROVIDER.anthropic]
-        active           = "true"
-        base_url         = "https://api.anthropic.com/v1"
-        env_key          = "ANTHROPIC_API_KEY"
+        active             = "true"
+        type               = "anthropic"
+        base_url           = "https://api.anthropic.com/v1"
+        env_key            = "ANTHROPIC_API_KEY"
         api_version_header = "2023-06-01"
-        default_model    = "claude-haiku-4-5"
-        supports_cache   = "true"
-        fallback_to      = "gemini"
+        default_model      = "claude-haiku-5-5"
+        supports_cache     = "true"
+        fallback_to        = "gemini"
         [LLM_PROVIDER.anthropic_END]
     """
 
@@ -187,35 +310,26 @@ class AnthropicProvider(BaseProvider):
     _CHARS_PER_TOKEN = 4
     _CACHE_MIN_TOKENS = 1024
 
+    def __init__(self, name: str, cfg: dict):
+        super().__init__(name, cfg)
+        self.api_version = cfg.get("api_version_header", "2023-06-01")
+
     def _is_cacheable(self, text: str) -> bool:
         """Estimate if text is long enough to benefit from caching."""
         return len(text) >= self._CACHE_MIN_TOKENS * self._CHARS_PER_TOKEN
 
-    async def complete(
-        self,
-        prompt: str,
-        model: str = None,
-        max_tokens: int = 1024,
-        system: str = None,
-    ) -> str:
-        cfg = config.get_active_llm_providers().get("anthropic", {})
-
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024,
+                       system: str = None):
         headers = {
             "x-api-key":         self.key,
-            "anthropic-version": cfg.get("api_version_header", "2023-06-01"),
+            "anthropic-version": self.api_version,
             "content-type":      "application/json",
         }
 
-        # --- Build user content ---
-        # Add cache_control if caching enabled + prompt long enough
+        # --- Build user content (cache_control if enabled + long enough) ---
         if self.supports_cache and self._is_cacheable(prompt):
-            user_content = [
-                {
-                    "type":          "text",
-                    "text":          prompt,
-                    "cache_control": {"type": "ephemeral"},
-                }
-            ]
+            user_content = [{"type": "text", "text": prompt,
+                             "cache_control": {"type": "ephemeral"}}]
             headers["anthropic-beta"] = "prompt-caching-2024-07-31"
             logger.debug("Anthropic: prompt cache_control applied to user message.")
         else:
@@ -230,20 +344,21 @@ class AnthropicProvider(BaseProvider):
         # --- Optional system prompt with cache_control ---
         if system:
             if self.supports_cache and self._is_cacheable(system):
-                payload["system"] = [
-                    {
-                        "type":          "text",
-                        "text":          system,
-                        "cache_control": {"type": "ephemeral"},
-                    }
-                ]
+                payload["system"] = [{"type": "text", "text": system,
+                                      "cache_control": {"type": "ephemeral"}}]
                 headers["anthropic-beta"] = "prompt-caching-2024-07-31"
                 logger.debug("Anthropic: prompt cache_control applied to system prompt.")
             else:
                 payload["system"] = system
 
         data = await self._post(f"{self.base_url}/messages", headers, payload)
-        return data["content"][0]["text"]
+        text = data["content"][0]["text"]
+        u = data.get("usage") or {}
+        tin = None
+        if u:
+            tin = sum(int(u.get(k) or 0) for k in
+                      ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"))
+        return text, _usage(tin, u.get("output_tokens"))
 
 
 # --- Gemini ------------------------------------------------------------------
@@ -251,222 +366,71 @@ class GeminiProvider(BaseProvider):
     """
     Google Gemini API — generateContent endpoint.
 
-    Implicit Caching (always active on Gemini side, no code needed):
-        Google automatically caches repeated prompt prefixes server-side.
-        No extra API call, no cache key, no TTL management needed.
-        Just send the same prompt structure and Gemini handles the rest.
-        supports_cache = "true" in .pyfun logs cache hint only.
-
-    Explicit Context Caching (NOT implemented here — when to use it):
-        Only worth the extra API complexity for very large static contexts
-        (32k+ tokens, e.g. large documents sent on every request).
-        Requires separate POST to /cachedContents, returns a cache_name,
-        which is then referenced in generateContent as cachedContent.name.
-        Implement as a separate tool (cache_create / cache_use) when needed.
+    Implicit Caching (always active on Gemini side, no code needed).
+    Explicit Context Caching is NOT implemented (only worth it for 32k+ static contexts).
 
     .pyfun block:
         [LLM_PROVIDER.gemini]
         active         = "true"
+        type           = "gemini"
         base_url       = "https://generativelanguage.googleapis.com/v1beta"
         env_key        = "GEMINI_API_KEY"
-        default_model  = "gemini-2.0-flash"
+        default_model  = "gemini-2.5-flash"
         supports_cache = "true"
         fallback_to    = "openrouter"
         [LLM_PROVIDER.gemini_END]
     """
 
-    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
+    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024,
+                       system: str = None):
         m        = model or self.model
         safe_url = f"{self.base_url}/models/{m}:generateContent"
 
         if self.supports_cache:
             logger.debug(f"Gemini: implicit caching active for model {m} (server-side, automatic).")
 
+        body = {
+            "contents":         [{"parts": [{"text": prompt}]}],
+            "generationConfig": {"maxOutputTokens": max_tokens},
+        }
+        if system:
+            body["systemInstruction"] = {"parts": [{"text": system}]}
+
         async with httpx.AsyncClient() as client:
             r = await client.post(
                 safe_url,
                 params={"key": self.key},  # key in query param, never in logs
-                json={
-                    "contents":         [{"parts": [{"text": prompt}]}],
-                    "generationConfig": {"maxOutputTokens": max_tokens},
-                },
+                json=body,
                 timeout=self.timeout,
             )
             try:
                 r.raise_for_status()
             except httpx.HTTPStatusError as e:
-                raise RuntimeError(
-                    f"HTTP {e.response.status_code} from {safe_url}"
+                raise ProviderError(
+                    f"HTTP {e.response.status_code} from {safe_url}",
+                    e.response.status_code,
                 ) from None
-            return r.json()["candidates"][0]["content"]["parts"][0]["text"]
-
-
-# --- OpenRouter ---------------------------------------------------------------
-class OpenRouterProvider(BaseProvider):
-    """OpenRouter API — OpenAI-compatible chat completions endpoint.
-
-    Required headers: HTTP-Referer + X-Title (required by OpenRouter for
-    free models and rate limit attribution).
-    """
+            data = r.json()
 
-    async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
-        data = await self._post(
-            f"{self.base_url}/chat/completions",
-            headers={
-                "Authorization": f"Bearer {self.key}",
-                "HTTP-Referer":  os.getenv("APP_URL", "https://huggingface.co"),
-                "X-Title":       os.getenv("HUB_NAME", "Universal AI Hub"),  # required!
-                "content-type":  "application/json",
-            },
-            payload={
-                "model":      model or self.model,
-                "max_tokens": max_tokens,
-                "messages":   [{"role": "user", "content": prompt}],
-            },
-        )
-        return data["choices"][0]["message"]["content"]
-
-
-# --- HuggingFace --------------------------------------------------------------
-class HuggingFaceProvider(BaseProvider):
-    """HuggingFace Inference API — OpenAI-compatible serverless endpoint.
-
-    base_url in .pyfun: https://api-inference.huggingface.co/v1
-    Model goes in payload, not in URL.
-    Free tier: max ~8B models. PRO required for 70B+.
-    """
-
-    async def complete(self, prompt: str, model: str = None, max_tokens: int = 512) -> str:
-        m    = model or self.model
-        data = await self._post(
-            f"{self.base_url}/chat/completions",
-            headers={
-                "Authorization": f"Bearer {self.key}",
-                "content-type":  "application/json",
-            },
-            payload={
-                "model":      m,
-                "max_tokens": max_tokens,
-                "messages":   [{"role": "user", "content": prompt}],
-            },
-        )
-        return data["choices"][0]["message"]["content"]
-
-
-# =============================================================================
-# DUMMY PROVIDERS — copy, uncomment, adapt
-# Steps: (1) uncomment class  (2) add to _PROVIDER_CLASSES  (3) add to .pyfun
-# =============================================================================
-
-# --- OpenAI -------------------------------------------------------------------
-# .pyfun block to add:
-#
-#   [LLM_PROVIDER.openai]
-#   active        = "true"
-#   base_url      = "https://api.openai.com/v1"
-#   env_key       = "OPENAI_API_KEY"
-#   default_model = "gpt-4o-mini"
-#   models        = "gpt-4o, gpt-4o-mini, gpt-3.5-turbo"
-#   fallback_to   = ""
-#   [LLM_PROVIDER.openai_END]
-#
-# class OpenAIProvider(BaseProvider):
-#     """OpenAI API — OpenAI-compatible chat completions endpoint."""
-#
-#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
-#         data = await self._post(
-#             f"{self.base_url}/chat/completions",
-#             headers={
-#                 "Authorization": f"Bearer {self.key}",
-#                 "content-type":  "application/json",
-#             },
-#             payload={
-#                 "model":      model or self.model,
-#                 "max_tokens": max_tokens,
-#                 "messages":   [{"role": "user", "content": prompt}],
-#             },
-#         )
-#         return data["choices"][0]["message"]["content"]
-
-
-# --- Mistral ------------------------------------------------------------------
-# .pyfun block to add:
-#
-#   [LLM_PROVIDER.mistral]
-#   active        = "true"
-#   base_url      = "https://api.mistral.ai/v1"
-#   env_key       = "MISTRAL_API_KEY"
-#   default_model = "mistral-large-latest"
-#   models        = "mistral-large-latest, mistral-small-latest, codestral-latest"
-#   fallback_to   = ""
-#   [LLM_PROVIDER.mistral_END]
-#
-# class MistralProvider(BaseProvider):
-#     """Mistral AI API — OpenAI-compatible chat completions endpoint."""
-#
-#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
-#         data = await self._post(
-#             f"{self.base_url}/chat/completions",
-#             headers={
-#                 "Authorization": f"Bearer {self.key}",
-#                 "content-type":  "application/json",
-#             },
-#             payload={
-#                 "model":      model or self.model,
-#                 "max_tokens": max_tokens,
-#                 "messages":   [{"role": "user", "content": prompt}],
-#             },
-#         )
-#         return data["choices"][0]["message"]["content"]
-
-
-# --- xAI (Grok) ---------------------------------------------------------------
-# .pyfun block to add:
-#
-#   [LLM_PROVIDER.xai]
-#   active        = "true"
-#   base_url      = "https://api.x.ai/v1"
-#   env_key       = "XAI_API_KEY"
-#   default_model = "grok-3-mini"
-#   models        = "grok-3, grok-3-mini, grok-3-fast"
-#   fallback_to   = ""
-#   [LLM_PROVIDER.xai_END]
-#
-# class XAIProvider(BaseProvider):
-#     """xAI Grok API — OpenAI-compatible chat completions endpoint."""
-#
-#     async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str:
-#         data = await self._post(
-#             f"{self.base_url}/chat/completions",
-#             headers={
-#                 "Authorization": f"Bearer {self.key}",
-#                 "content-type":  "application/json",
-#             },
-#             payload={
-#                 "model":      model or self.model,
-#                 "max_tokens": max_tokens,
-#                 "messages":   [{"role": "user", "content": prompt}],
-#             },
-#         )
-#         return data["choices"][0]["message"]["content"]
+        text = data["candidates"][0]["content"]["parts"][0]["text"]
+        meta = data.get("usageMetadata") or {}
+        return text, _usage(meta.get("promptTokenCount"), meta.get("candidatesTokenCount"))
 
 
 # =============================================================================
 # SECTION 3 — Provider Registry
 # Built from .pyfun [LLM_PROVIDERS] at initialize().
-# Maps provider names → classes.
-# To activate a dummy: uncomment class above + add entry here.
+# Handler is chosen by the `type` field of the block (default: the block name).
+#   type = "openai_compat" → OpenAICompatProvider (generic, no code per provider)
+#   type = "anthropic"     → AnthropicProvider
+#   type = "gemini"        → GeminiProvider
+# New API format = new class above + one line here.
 # =============================================================================
 
-_PROVIDER_CLASSES = {
-    "smollm":      SmolLMProvider,
-    "anthropic":   AnthropicProvider,
-    "gemini":      GeminiProvider,
-    "openrouter":  OpenRouterProvider,
-    "huggingface": HuggingFaceProvider,
-    # "openai":   OpenAIProvider,    # ← uncomment to activate
-    # "mistral":  MistralProvider,   # ← uncomment to activate
-    # "xai":      XAIProvider,       # ← uncomment to activate
+_TYPE_CLASSES = {
+    "openai_compat": OpenAICompatProvider,
+    "anthropic":     AnthropicProvider,
+    "gemini":        GeminiProvider,
 }
 
 _registry: dict = {}
@@ -474,7 +438,7 @@ _registry: dict = {}
 
 def initialize() -> None:
     """
-    Build provider registry from .pyfun [LLM_PROVIDERS].
+    Build provider registries from .pyfun [LLM_PROVIDERS] + [SEARCH_PROVIDERS].
     Called once by mcp.py during startup sequence.
     Skips providers with missing ENV keys — no crash, just fewer tools.
     """
@@ -486,25 +450,70 @@ def initialize() -> None:
         if not env_key or not os.getenv(env_key):
             logger.info(f"Provider '{name}' skipped — ENV key not set.")
             continue
-        cls = _PROVIDER_CLASSES.get(name)
+        ptype = (cfg.get("type") or name).strip().lower()
+        cls = _TYPE_CLASSES.get(ptype)
         if not cls:
-            logger.info(f"Provider '{name}' has no handler yet — skipped.")
+            logger.info(f"Provider '{name}' has no handler (type '{ptype}') — skipped.")
             continue
         _registry[name] = cls(name, cfg)
         cache_hint = " [cache: ON]" if cfg.get("supports_cache", "false") == "true" else ""
-        logger.info(f"Provider registered: {name}{cache_hint}")
+        logger.info(f"Provider registered: {name} (type: {ptype}){cache_hint}")
+
+    # Search providers — same key-gating principle
+    _initialize_search()
 
 
 # =============================================================================
 # SECTION 4 — LLM Execution + Fallback Chain
 # =============================================================================
 
+def provider_for_model(model: str) -> Optional[str]:
+    """
+    Provider that owns `model` according to .pyfun [MODELS] (provider field).
+    None if the model is unknown → caller keeps its default provider.
+    """
+    if not model:
+        return None
+    entry = models_mod.get(model) or {}
+    return entry.get("provider") or None
+
+
+def _clamp_tokens(model: str, max_tokens: int) -> int:
+    """Hard cap (MAX_TOKENS_CAP) + per-model max_output_tokens (manual or auto-pricing)."""
+    try:
+        n = max(1, int(max_tokens))
+    except (TypeError, ValueError):
+        n = 1024
+    cap = _limit("MAX_TOKENS_CAP", 8192)
+    if cap > 0:
+        n = min(n, cap)
+    lim = pricing.max_output_for(model)
+    if lim:
+        n = min(n, lim)
+    return n
+
+
+async def _record_usage(tool: str, provider: str, model: str, usage: dict, latency_ms: int) -> None:
+    """Log usage + estimated cost. NEVER raises — accounting must not break a call."""
+    try:
+        tin, tout = usage.get("input"), usage.get("output")
+        cost = None
+        if tin is not None or tout is not None:
+            cost = await pricing.cost_for(model, tin, tout)
+        await db_sync.log_usage(tool, provider, model, tin, tout, cost, latency_ms)
+        cost_txt = f"${cost:.6f}" if cost is not None else "n/a"
+        logger.info(f"Usage: {provider}/{model} in={tin} out={tout} cost≈{cost_txt} ({latency_ms} ms)")
+    except Exception as e:
+        logger.debug(f"Usage logging skipped: {type(e).__name__}")
+
+
 async def llm_complete(
     prompt: str,
     provider_name: str = None,
     model: str = None,
     max_tokens: int = 1024,
     system: str = None,
+    tool_name: str = "llm_complete",
 ) -> str:
     """
     Send prompt to LLM provider with automatic fallback chain.
@@ -513,49 +522,53 @@ async def llm_complete(
 
     Args:
         prompt:        Input text to send to the model.
-        provider_name: Provider name override. Defaults to default_provider
-                       from .pyfun [TOOL.llm_complete].
-        model:         Model name override. Defaults to provider's default_model.
-        max_tokens:    Max tokens in response. Default: 1024.
-        system:        Optional system prompt. Passed to providers that support it.
-                       AnthropicProvider caches it automatically if supports_cache = true
-                       and the system prompt is long enough (>= ~1024 tokens).
+        provider_name: Provider override. Unknown / non-LLM names are ignored.
+                       If only `model` is given, the provider is derived from [MODELS].
+        model:         Model override — applies to the FIRST provider only.
+        max_tokens:    Max tokens in response (clamped, see header).
+        system:        Optional system prompt — sent as real system prompt to every provider.
+        tool_name:     Only used for the usage log.
 
     Returns:
-        Model response as plain text string.
+        "[provider] text"
     """
+    model = (model or "").strip() or None
+    if provider_name and provider_name not in config.get_llm_providers():
+        logger.debug(f"'{provider_name}' is not an LLM provider — using default.")
+        provider_name = None
+    if not provider_name:
+        provider_name = provider_for_model(model)
     if not provider_name:
         tools_cfg     = config.get_active_tools()
         provider_name = tools_cfg.get("llm_complete", {}).get("default_provider", "anthropic")
 
     visited = set()
     current = provider_name
+    first   = True
 
     while current and current not in visited:
         visited.add(current)
-        provider = _registry.get(current)
+        provider  = _registry.get(current)
+        use_model = model if first else None   # explicit model belongs to the first provider only
+        first     = False
 
         if not provider:
             logger.warning(f"Provider '{current}' not in registry — trying fallback.")
         else:
+            m  = use_model or provider.model
+            mt = _clamp_tokens(m, max_tokens)
             try:
-                # Pass system prompt if provider supports it (Anthropic)
-                # Other providers accept **kwargs and ignore unknown params safely
-                if system is not None and hasattr(provider, 'complete'):
-                    import inspect
-                    sig = inspect.signature(provider.complete)
-                    if 'system' in sig.parameters:
-                        result = await provider.complete(prompt, model, max_tokens, system=system)
-                    else:
-                        result = await provider.complete(prompt, model, max_tokens)
-                else:
-                    result = await provider.complete(prompt, model, max_tokens)
-
+                t0 = time.monotonic()
+                text, usage = await _with_retry(
+                    current,
+                    lambda p=provider, um=use_model, n=mt: p.complete(prompt, um, n, system=system),
+                )
+                latency_ms = int((time.monotonic() - t0) * 1000)
                 logger.info(f"Response from provider: '{current}'")
-                return f"[{current}] {result}"
+                await _record_usage(tool_name, current, m, usage, latency_ms)
+                return f"[{current}] {text}"
             except Exception as e:
-                # Log only exception type + sanitized message — never raw {e}
-                # which may contain headers, keys, or response bodies
+                # Log only exception type + sanitized message — never raw headers/keys/bodies
                 logger.warning(
                     f"Provider '{current}' failed: {type(e).__name__}: {e} — trying fallback."
                 )
@@ -572,9 +585,289 @@ complete = llm_complete
 
 # =============================================================================
 # SECTION 5 — Search Execution
-# Search providers not yet implemented — returns placeholder.
-# Add BraveProvider, TavilyProvider here when ready.
+# Same pattern as LLM providers: class + _SEARCH_PROVIDER_CLASSES + fallback.
+# Adding a search provider = add class + register + .pyfun block. Nothing else.
+# =============================================================================
+
+class BaseSearchProvider:
+    """
+    Base class for all search providers.
+    Subclasses only implement search() — HTTP logic lives here.
+    """
+    def __init__(self, name: str, cfg: dict):
+        self.name        = name
+        self.key         = os.getenv(cfg.get("env_key", ""))
+        self.base_url    = cfg.get("base_url", "")
+        self.fallback    = cfg.get("fallback_to", "")
+        self.timeout     = int(config.get_limits().get("SEARCH_TIMEOUT_SEC", "30"))
+        self.default_results = int(cfg.get("default_results", "5"))
+        self.max_results     = int(cfg.get("max_results", "20"))
+        self._key_hint = (
+            f"{self.key[:4]}...{self.key[-4:]}"
+            if self.key and len(self.key) > 8
+            else "***"
+        )
+
+    async def search(self, query: str, max_results: int) -> str:
+        """Override in each search provider subclass."""
+        raise NotImplementedError
+
+    async def _get(self, url: str, headers: dict, params: dict) -> dict:
+        """Shared HTTP GET with sanitized errors (never leak keys/bodies)."""
+        safe_url = url.split("?")[0]
+        async with httpx.AsyncClient() as client:
+            r = await client.get(url, headers=headers, params=params, timeout=self.timeout)
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise ProviderError(f"HTTP {e.response.status_code} from {safe_url}", e.response.status_code) from None
+            return r.json()
+
+    async def _get_text(self, url: str, headers: dict, params: dict) -> str:
+        """Shared HTTP GET returning the raw body (HTML) — sanitized errors."""
+        safe_url = url.split("?")[0]
+        async with httpx.AsyncClient() as client:
+            r = await client.get(url, headers=headers, params=params, timeout=self.timeout)
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise ProviderError(f"HTTP {e.response.status_code} from {safe_url}", e.response.status_code) from None
+            return r.text
+
+    async def _post(self, url: str, headers: dict, payload: dict) -> dict:
+        """Shared HTTP POST with sanitized errors."""
+        safe_url = url.split("?")[0]
+        async with httpx.AsyncClient() as client:
+            r = await client.post(url, headers=headers, json=payload, timeout=self.timeout)
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                raise ProviderError(f"HTTP {e.response.status_code} from {safe_url}", e.response.status_code) from None
+            return r.json()
+
+    def _clip(self, max_results: int) -> int:
+        """Clamp requested results into [1, max_results]."""
+        try:
+            n = int(max_results)
+        except (TypeError, ValueError):
+            n = self.default_results
+        return max(1, min(n, self.max_results))
+
+
+# --- Brave Search ---------------------------------------------------------------
+class BraveSearchProvider(BaseSearchProvider):
+    """
+    Brave Search API — web search endpoint.
+    Auth via X-Subscription-Token header (NOT Bearer!).
+
+    .pyfun block:
+        [SEARCH_PROVIDER.brave]
+        active          = "true"
+        base_url        = "https://api.search.brave.com/res/v1/web/search"
+        env_key         = "BRAVE_API_KEY"
+        default_results = "5"
+        max_results     = "20"
+        fallback_to     = "tavily"
+        [SEARCH_PROVIDER.brave_END]
+    """
+
+    async def search(self, query: str, max_results: int = 5) -> str:
+        data = await self._get(
+            self.base_url,
+            headers={
+                "X-Subscription-Token": self.key,
+                "Accept":              "application/json",
+                "Accept-Encoding":     "gzip",
+            },
+            params={
+                "q":     query,
+                "count": self._clip(max_results),
+            },
+        )
+        results = data.get("web", {}).get("results", [])
+        if not results:
+            raise RuntimeError("Brave returned no results")
+        lines = [f"[{self.name}] Search results for: '{query}'"]
+        for i, r in enumerate(results, 1):
+            lines.append(f"{i}. {r.get('title', '')}\n   {r.get('url', '')}\n   {r.get('description', '')}")
+        return "\n\n".join(lines)
+
+
+# --- Tavily ---------------------------------------------------------------------
+class TavilySearchProvider(BaseSearchProvider):
+    """
+    Tavily Search API — AI-optimized web search.
+    include_answer = "true" in .pyfun → adds AI-synthesized answer on top.
+
+    .pyfun block:
+        [SEARCH_PROVIDER.tavily]
+        active          = "true"
+        base_url        = "https://api.tavily.com/search"
+        env_key         = "TAVILY_API_KEY"
+        default_results = "5"
+        max_results     = "10"
+        include_answer  = "true"
+        fallback_to     = ""
+        [SEARCH_PROVIDER.tavily_END]
+    """
+
+    def __init__(self, name: str, cfg: dict):
+        super().__init__(name, cfg)
+        self.include_answer = cfg.get("include_answer", "false").lower() == "true"
+
+    async def search(self, query: str, max_results: int = 5) -> str:
+        data = await self._post(
+            self.base_url,
+            headers={"Content-Type": "application/json"},
+            payload={
+                "api_key":       self.key,   # Tavily takes the key in the payload
+                "query":         query,
+                "max_results":   self._clip(max_results),
+                "include_answer": self.include_answer,
+            },
+        )
+        results = data.get("results", [])
+        if not results and not data.get("answer"):
+            raise RuntimeError("Tavily returned no results")
+        lines = [f"[{self.name}] Search results for: '{query}'"]
+        if self.include_answer and data.get("answer"):
+            lines.append(f"AI answer: {data['answer']}")
+        for i, r in enumerate(results, 1):
+            lines.append(f"{i}. {r.get('title', '')}\n   {r.get('url', '')}\n   {r.get('content', '')}")
+        return "\n\n".join(lines)
+
+
+# --- DuckDuckGo (keyless, gentle last-resort fallback) --------------------------
+class _DDGParser(HTMLParser):
+    """Minimal parser for html.duckduckgo.com result pages (stdlib only, no BeautifulSoup)."""
+    def __init__(self):
+        super().__init__()
+        self.results: list = []
+        self._mode = None
+        self._cur = None
+        self._buf: list = []
+
+    @staticmethod
+    def _unwrap(href: str) -> str:
+        """DDG wraps targets as //duckduckgo.com/l/?uddg=<urlencoded>&rut=… → real URL."""
+        target = (parse_qs(urlparse(href).query).get("uddg") or [href])[0]
+        return "https:" + target if target.startswith("//") else target
+
+    def handle_starttag(self, tag, attrs):
+        if tag != "a":
+            return
+        a   = dict(attrs)
+        cls = (a.get("class") or "").split()
+        if "result__a" in cls:
+            self._cur = {"title": "", "url": self._unwrap(a.get("href") or ""), "snippet": ""}
+            self.results.append(self._cur)
+            self._mode, self._buf = "title", []
+        elif "result__snippet" in cls and self.results:
+            self._cur = self.results[-1]
+            self._mode, self._buf = "snippet", []
+
+    def handle_data(self, data):
+        if self._mode:
+            self._buf.append(data)
+
+    def handle_endtag(self, tag):
+        if tag == "a" and self._mode:
+            self._cur[self._mode] = " ".join("".join(self._buf).split())
+            self._mode = None
+
+
+class DuckDuckGoSearchProvider(BaseSearchProvider):
+    """
+    Keyless search fallback (idea: "GentleSearchProvider").
+
+    DuckDuckGo has NO official search API — this reads the public HTML endpoint, so it is
+    fragile by nature and gentle by design:
+      - global cooldown (min_interval_sec, default 300): called too early it RAISES, so the
+        fallback chain reports an honest failure instead of a fake "result" string
+      - the attempt counts for the cooldown even if it fails (no hammering a blocked endpoint)
+      - honest User-Agent, no evasion tricks, no retries
+      - captcha / layout change = no parsable results = clear error
+
+    .pyfun block (no key needed → requires_key = "false"):
+        [SEARCH_PROVIDER.duckduckgo]
+        active = "false"   requires_key = "false"
+        base_url = "https://html.duckduckgo.com/html/"
+        min_interval_sec = "300"   # optional   user_agent = "..."   # optional
+    """
+    def __init__(self, name: str, cfg: dict):
+        super().__init__(name, cfg)
+        self.base_url     = cfg.get("base_url") or "https://html.duckduckgo.com/html/"
+        self.min_interval = float(cfg.get("min_interval_sec", "300"))
+        self.user_agent   = cfg.get("user_agent") or "UniversalMCPHub/1.0 (+https://github.com/VolkanSah)"
+        self._last_call: Optional[float] = None
+
+    async def search(self, query: str, max_results: int) -> str:
+        now = time.monotonic()
+        if self._last_call is not None and now - self._last_call < self.min_interval:
+            wait = int(self.min_interval - (now - self._last_call))
+            raise ProviderError(f"DuckDuckGo cooldown — wait {wait}s (min_interval_sec={int(self.min_interval)})")
+        self._last_call = now   # counts even if the request fails
+
+        try:
+            html = await self._get_text(
+                self.base_url,
+                headers={
+                    "User-Agent":      self.user_agent,
+                    "Accept":          "text/html,application/xhtml+xml",
+                    "Accept-Language": "de,en-US;q=0.7,en;q=0.3",
+                    "DNT":             "1",
+                },
+                params={"q": query},
+            )
+        except ProviderError as e:
+            raise ProviderError(str(e)) from None   # drop status → never retried (gentle)
+
+        parser = _DDGParser()
+        parser.feed(html)
+        hits = [r for r in parser.results if r["url"]][: self._clip(max_results)]
+        if not hits:
+            raise ProviderError("DuckDuckGo: no parsable results (blocked/captcha or layout changed)")
+
+        lines = [f"[{self.name}] Search results for: '{query}'"]
+        for i, r in enumerate(hits, 1):
+            lines.append(f"{i}. {r['title']}\n   {r['url']}\n   {r['snippet']}")
+        return "\n\n".join(lines)
+
+
 # =============================================================================
+# Search Registry — built from .pyfun [SEARCH_PROVIDERS] at initialize()
+# =============================================================================
+
+_SEARCH_PROVIDER_CLASSES = {
+    "brave":  BraveSearchProvider,
+    "tavily": TavilySearchProvider,
+    "duckduckgo": DuckDuckGoSearchProvider,   # keyless (requires_key = "false" in .pyfun)
+    # "serper": SerperSearchProvider,   # ← uncomment to activate
+}
+
+_search_registry: dict = {}
+
+
+def _initialize_search() -> None:
+    """
+    Build search provider registry from .pyfun [SEARCH_PROVIDERS].
+    Called inside initialize() — same key-gating as LLM providers:
+    no ENV key = provider skipped, no crash.
+    """
+    global _search_registry
+    for name, cfg in config.get_active_search_providers().items():
+        env_key = cfg.get("env_key", "")
+        needs_key = str(cfg.get("requires_key", "true")).lower() != "false"
+        if needs_key and (not env_key or not os.getenv(env_key)):
+            logger.info(f"Search provider '{name}' skipped — ENV key not set.")
+            continue
+        cls = _SEARCH_PROVIDER_CLASSES.get(name)
+        if not cls:
+            logger.info(f"Search provider '{name}' has no handler yet — skipped.")
+            continue
+        _search_registry[name] = cls(name, cfg)
+        logger.info(f"Search provider registered: {name}")
+
 
 async def search(
     query: str,
@@ -582,21 +875,49 @@ async def search(
     max_results: int = 5,
 ) -> str:
     """
-    Search the web via configured search provider.
-    Search providers not yet implemented — placeholder until BraveProvider ready.
+    Search the web via configured search provider with automatic fallback chain.
+    Fallback order is defined in .pyfun via fallback_to field.
+    Raises RuntimeError if all providers in the chain fail.
 
     Args:
         query:         Search query string.
         provider_name: Provider name override (e.g. 'brave', 'tavily').
+                       Defaults to default_provider from .pyfun [TOOL.web_search].
         max_results:   Maximum number of results. Default: 5.
 
     Returns:
         Formatted search results as plain text string.
     """
-    # TODO: implement BraveProvider, TavilyProvider
-    # Same pattern as LLM providers — add class + register in _SEARCH_REGISTRY
-    logger.info(f"web_search called — query: '{query}' — search providers not yet active.")
-    return f"Search not yet implemented. Query was: {query}"
+    if provider_name and provider_name not in config.get_search_providers():
+        logger.debug(f"'{provider_name}' is not a search provider — using default.")
+        provider_name = None
+    if not provider_name:
+        tools_cfg     = config.get_active_tools()
+        provider_name = tools_cfg.get("web_search", {}).get("default_provider", "brave")
+
+    visited = set()
+    current = provider_name
+
+    while current and current not in visited:
+        visited.add(current)
+        provider = _search_registry.get(current)
+
+        if not provider:
+            logger.warning(f"Search provider '{current}' not in registry — trying fallback.")
+        else:
+            try:
+                result = await _with_retry(current, lambda p=provider: p.search(query, max_results))
+                logger.info(f"Search response from provider: '{current}'")
+                return result
+            except Exception as e:
+                logger.warning(
+                    f"Search provider '{current}' failed: {type(e).__name__}: {e} — trying fallback."
+                )
+
+        cfg     = config.get_active_search_providers().get(current, {})
+        current = cfg.get("fallback_to", "")
+
+    raise RuntimeError("All search providers failed — no fallback available.")
 
 
 # =============================================================================
@@ -610,12 +931,8 @@ def list_active_llm() -> list:
 
 
 def list_active_search() -> list:
-    """
-    Returns list of active search provider names.
-    Empty until search providers are implemented.
-    """
-    # TODO: return list(_search_registry.keys()) when search providers are ready
-    return []
+    """Returns list of active search provider names."""
+    return list(_search_registry.keys())
 
 
 def get(name: str) -> BaseProvider:

app/shellmaster.py

@@ -33,6 +33,8 @@
 
 import json
 import logging
+import os
+import re
 import httpx
 from pathlib import Path
 from typing import Optional
@@ -89,9 +91,23 @@ _HARDCODED_BLOCKED = {
 }
 
 
+# rm with a recursive flag in ANY order/position (-rf, -fr, -r -f, --recursive) aimed at
+# root, home, wildcard or the current/parent dir. Plain substring matching on "rm -rf /"
+# misses "rm -fr /" and "rm -r -f /".
+_RM_DANGEROUS = re.compile(
+    r"\brm\s+(?:-\S+\s+)*(?:-\S*r\S*|--recursive)\s+(?:-\S+\s+)*(?:/(?:\s|$|\*)|~|\*|\$home|\.\.?(?:\s|$))"
+)
+
+# Shell metacharacters that chain / redirect / substitute commands. A registry command is
+# matched by its FIRST token only, so "ls; rm x" would otherwise pass as "ls".
+_SHELL_META = re.compile(r"[;&|`<>\n\r]|\$\(|\$\{")
+
+
 def _is_hardblocked(cmd_str: str) -> bool:
     """Check if command contains any hardcoded blocked pattern."""
-    cmd_lower = cmd_str.lower().strip()
+    cmd_lower = " ".join(cmd_str.lower().split())   # normalize whitespace
+    if _RM_DANGEROUS.search(cmd_lower):
+        return True
     return any(blocked in cmd_lower for blocked in _HARDCODED_BLOCKED)
 
 
@@ -125,7 +141,13 @@ async def initialize() -> None:
         return
 
     _agent_url = _cfg.get("shellmaster_agent_url", "http://localhost:5004")
-    _token     = _cfg.get("shellmaster_token", "")
+    # Token: ENV zuerst (shellmaster_env_key → .env, Guardian lädt ENV) —
+    # das .pyfun-Feld ist nur noch Fallback. Secrets gehören NICHT in .pyfun
+    # (gleiche Regel wie bei allen Providern: env_key = NAME, Wert in .env).
+    env_key  = _cfg.get("shellmaster_env_key", "")
+    _token   = os.getenv(env_key, "") if env_key else ""
+    if not _token:
+        _token = _cfg.get("shellmaster_token", "")
     _timeout   = int(_cfg.get("timeout_sec", "30"))
 
     # Command registry — local file first
@@ -184,15 +206,23 @@ def _validate_command(cmd_str: str) -> tuple[bool, str]:
     if _is_hardblocked(cmd_str):
         return False, "blocked by system policy"
 
-    # Match against registry
+    # No chaining / redirection / substitution — one command, nothing else
+    if _SHELL_META.search(cmd_str):
+        return False, "shell metacharacters (; & | ` < > $( ) are not allowed"
+
+    # Match against registry — FIRST TOKEN must equal the template's first token
     registry = _load_registry()
-    cmd_lower = cmd_str.lower().strip()
+    tokens = cmd_str.lower().split()
+    if not tokens:
+        return False, "empty command"
 
     for cmd_id, cmd in registry.items():
         # Check both unix and win templates
         for os_key in ("unix", "win"):
-            template_base = cmd.get(os_key, "").split()[0].lower()
-            if template_base and cmd_lower.startswith(template_base):
+            parts = (cmd.get(os_key) or "").split()   # empty template (e.g. unix-only command) → skip
+            if not parts:
+                continue
+            if tokens[0] == parts[0].lower():
                 if not cmd.get("allowed", False):
                     return False, f"command '{cmd_id}' is blocked in registry"
                 return True, cmd_id

app/skills/README.md

@@ -0,0 +1,14 @@
+# app/skills/ — System-Prompts als Dateien
+
+Eine Markdown-Datei hier = ein "Skill" für ein LLM-Tool. In `app/.pyfun`:
+
+    [TOOL.mein_tool]
+    provider_type      = "llm"
+    system_prompt_file = "mein_skill.md"     # wird NACH system_prompt angehängt (falls beides gesetzt)
+
+- Nur `.md` / `.txt`, nur direkt in diesem Ordner (kein `../`), max. 20 000 Zeichen.
+- Es wird **nur Text gelesen** und als `system`-Prompt gesendet. Aus diesem Ordner wird nie Code
+  importiert oder ausgeführt — eine Datei hier kann nichts ausführen.
+- Änderungen werden nach einem Neustart wirksam (Cache). Fehlende Datei = Warnung beim Start.
+- Skills von Dritten (z. B. Neons Agent-Skills) sind Anleitungen für Coding-Agents und gehören
+  nicht ungeprüft hierher — vorher lesen.

app/skills_db.py

@@ -0,0 +1,227 @@
+# =============================================================================
+# app/skills_db.py
+# Read-only access to the skill databases built by local_tools/vector_hub/secure_vectorizer.py
+# Universal MCP Hub (Sandboxed) - based on PyFundaments Architecture
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# =============================================================================
+# LAYOUT (app/db/skills/):
+#   core/core.db        → CORE: the main skill with all restrictions. Never exposed through tools.
+#                         Optionally injected as system-prompt prefix (SKILLS_INJECT_CORE / use_core).
+#   core/<other>.db     → AGENT: reference for agents (e.g. core_agent.db). Searchable, not injected.
+#   user/*.db           → USER skills (autoload). Searchable; best chunks can be injected per
+#                         request (SKILLS_INJECT_RELEVANT / use_skills).
+#
+# WHAT IS USED: FTS5 / BM25 keyword search (same query + weights as the vectorizer).
+#   The optional semantic vectors (vec BLOB) are ignored — no embedding dependency in the hub.
+#
+# SAFETY:
+#   - DBs are opened READ-ONLY (mode=ro); nothing here writes, imports or executes skill content.
+#   - Skill text is plain data that ends up in a system prompt — only ship DBs you built yourself.
+#   - A broken / foreign DB (wrong schema) is skipped with a warning — never a crash.
+#   - SHIP DBs CHECKPOINTED: PRAGMA wal_checkpoint(TRUNCATE); PRAGMA journal_mode=DELETE;
+#     and do not commit the *.db-wal / *.db-shm files.
+# =============================================================================
+import asyncio
+import logging
+import re
+import shutil
+import sqlite3
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import config
+
+logger = logging.getLogger("skills_db")
+
+_ROOT   = Path(__file__).resolve().parent / "db" / "skills"
+_TOKEN  = re.compile(r"\w+", re.UNICODE)
+_NEEDED = {"chunks", "tags", "meta", "fts"}
+
+_dbs: Dict[str, List[Path]] = {"core": [], "agent": [], "user": []}
+_open_as: Dict[Path, tuple] = {}     # db path → (target, use_uri)
+_core_text = ""
+_active = False
+
+
+# ---------------------------------------------------------------------------
+# Open / validate
+# ---------------------------------------------------------------------------
+
+def _connect(path: Path) -> sqlite3.Connection:
+    target, uri = _open_as[path]
+    return sqlite3.connect(target, uri=uri)
+
+
+def _validate(path: Path) -> bool:
+    """Open read-only, check schema. WAL on a read-only dir → fall back to a private copy."""
+    attempts = [(f"{path.resolve().as_uri()}?mode=ro", True), None]
+    for attempt in attempts:
+        if attempt is None:   # fallback: private temp copy (db + wal/shm), opened normally
+            tmp = Path(tempfile.mkdtemp(prefix="skills_"))
+            for suffix in ("", "-wal", "-shm"):
+                src = Path(str(path) + suffix)
+                if src.exists():
+                    shutil.copy2(src, tmp / src.name)
+            attempt = (str(tmp / path.name), False)
+        try:
+            c = sqlite3.connect(attempt[0], uri=attempt[1])
+            names = {r[0] for r in c.execute("SELECT name FROM sqlite_master")}
+            if not _NEEDED <= names:
+                c.close()
+                logger.warning(f"Skills DB '{path.name}' skipped — not a vectorizer DB (missing {sorted(_NEEDED - names)}).")
+                return False
+            c.execute("SELECT 1 FROM chunks LIMIT 1").fetchall()
+            c.execute("SELECT rowid FROM fts WHERE fts MATCH 'x' LIMIT 1").fetchall()   # FTS5 available?
+            c.close()
+            _open_as[path] = attempt
+            return True
+        except sqlite3.Error as e:
+            last = type(e).__name__
+    logger.warning(f"Skills DB '{path.name}' skipped — cannot open read-only ({last}).")
+    return False
+
+
+def initialize() -> None:
+    """Scan app/db/skills/. Inactive or empty → stays inactive. Never raises."""
+    global _active, _core_text
+    cfg = config.get_skills()
+    if str(cfg.get("SKILLS_ACTIVE", "false")).lower() != "true":
+        logger.info("Skills DB not active in .pyfun [SKILLS] — skipped")
+        return
+    for k in _dbs:
+        _dbs[k].clear()
+    for path in sorted((_ROOT / "core").glob("*.db")) if (_ROOT / "core").is_dir() else []:
+        if _validate(path):
+            _dbs["core" if path.name == "core.db" else "agent"].append(path)
+    for path in sorted((_ROOT / "user").glob("*.db")) if (_ROOT / "user").is_dir() else []:
+        if _validate(path):
+            _dbs["user"].append(path)
+
+    # core text: all chunks of core.db, in order, capped
+    try:
+        cap = int(cfg.get("SKILLS_CORE_MAX_CHARS", "8000"))
+    except ValueError:
+        cap = 8000
+    parts = []
+    for p in _dbs["core"]:
+        c = _connect(p)
+        parts += [f"## {h}\n{t}" if h else t for h, t in c.execute("SELECT heading, text FROM chunks ORDER BY id")]
+        c.close()
+    _core_text = "\n\n".join(parts)[:cap]
+
+    _active = any(_dbs.values())
+    logger.info(f"Skills DB: core={len(_dbs['core'])} agent={len(_dbs['agent'])} user={len(_dbs['user'])} "
+                f"(core text: {len(_core_text)} chars)")
+
+
+def is_ready() -> bool:
+    return _active
+
+
+def core_text() -> str:
+    """The always-on core skill (restrictions). For system-prompt injection only — never via tools."""
+    return _core_text
+
+
+# ---------------------------------------------------------------------------
+# Search / catalog (sync, run in a thread by the async wrappers)
+# ---------------------------------------------------------------------------
+
+def _fts_query(q: str) -> str:
+    toks = _TOKEN.findall((q or "").lower())
+    return " OR ".join(f'"{t}"*' for t in toks)
+
+
+def _scope_paths(scope: str) -> List[Path]:
+    scope = (scope or "user").lower()
+    if scope == "all":                      # core is deliberately NOT included
+        return _dbs["agent"] + _dbs["user"]
+    if scope not in ("user", "agent"):
+        raise ValueError('scope must be "user", "agent" or "all"')
+    return _dbs[scope]
+
+
+def _search_sync(query: str, top_k: int, tag: str, scope: str) -> List[Dict[str, Any]]:
+    tag = (tag or "").strip().lower() or None
+    fq = _fts_query(query)
+    if not fq and not tag:
+        return []
+    out: List[Dict[str, Any]] = []
+    for path in _scope_paths(scope):
+        c = _connect(path)
+        try:
+            if fq:
+                sql, params = "SELECT rowid FROM fts WHERE fts MATCH ?", [fq]
+                if tag:
+                    sql += " AND rowid IN (SELECT c.id FROM chunks c JOIN tags t ON t.path=c.path WHERE t.tag=?)"
+                    params.append(tag)
+                sql += " ORDER BY bm25(fts, 5.0, 1.0) LIMIT ?"
+            else:
+                sql = ("SELECT id FROM chunks WHERE path IN (SELECT path FROM tags WHERE tag=?) "
+                       "ORDER BY id LIMIT ?")
+                params = [tag]
+            params.append(top_k)
+            for rank, (rid,) in enumerate(c.execute(sql, params).fetchall()):
+                row = c.execute(
+                    "SELECT c.path, c.heading, c.text, m.name FROM chunks c "
+                    "LEFT JOIN meta m ON m.path = c.path WHERE c.id = ?", (rid,)).fetchone()
+                if row:
+                    out.append({"skill": row[0], "name": row[3] or row[0], "heading": row[1],
+                                "text": row[2], "db": path.name, "rank": rank})
+        finally:
+            c.close()
+    out.sort(key=lambda r: r["rank"])       # best of each DB first (BM25 rank per DB)
+    return out[:top_k]
+
+
+def _catalog_sync(scope: str, tag: str) -> List[Dict[str, Any]]:
+    tag = (tag or "").strip().lower() or None
+    out: List[Dict[str, Any]] = []
+    for path in _scope_paths(scope):
+        c = _connect(path)
+        try:
+            for p, name, desc in c.execute("SELECT path, name, description FROM meta ORDER BY path"):
+                tags = [r[0] for r in c.execute("SELECT tag FROM tags WHERE path=? ORDER BY tag", (p,))]
+                if tag and tag not in tags:
+                    continue
+                n = c.execute("SELECT COUNT(*) FROM chunks WHERE path=?", (p,)).fetchone()[0]
+                out.append({"skill": p, "name": name, "description": desc, "tags": tags, "chunks": n, "db": path.name})
+        finally:
+            c.close()
+    return out
+
+
+async def search(query: str = "", top_k: int = 3, tag: str = "", scope: str = "user") -> List[Dict[str, Any]]:
+    """BM25 search over skill chunks. scope: user (default) | agent | all. core is never searchable."""
+    if not _active:
+        raise RuntimeError("Skills DB not active — set SKILLS_ACTIVE = \"true\" in .pyfun [SKILLS]")
+    top_k = max(1, min(int(top_k or 3), 10))
+    return await asyncio.to_thread(_search_sync, query, top_k, tag, scope)
+
+
+async def catalog(scope: str = "all", tag: str = "") -> List[Dict[str, Any]]:
+    """List skills (name, description, tags, chunk count). core is never listed."""
+    if not _active:
+        raise RuntimeError("Skills DB not active — set SKILLS_ACTIVE = \"true\" in .pyfun [SKILLS]")
+    return await asyncio.to_thread(_catalog_sync, scope, tag)
+
+
+async def context_for(prompt: str, top_k: int = 3, max_chars: int = 3000) -> str:
+    """Best matching USER skill chunks for a prompt, formatted for a system prompt ('' if none)."""
+    if not _active or not _dbs["user"] or not (prompt or "").strip():
+        return ""
+    try:
+        hits = await asyncio.to_thread(_search_sync, prompt, max(1, min(int(top_k), 10)), "", "user")
+    except Exception as e:
+        logger.warning(f"Skills lookup failed ({type(e).__name__}) — continuing without skills.")
+        return ""
+    parts, used = [], 0
+    for h in hits:
+        block = f"### {h['name']} — {h['heading']}\n{h['text']}" if h["heading"] else f"### {h['name']}\n{h['text']}"
+        if used + len(block) > max_chars:
+            break
+        parts.append(block)
+        used += len(block)
+    return ("Relevant skills for this request:\n\n" + "\n\n".join(parts)) if parts else ""

app/tools.py

@@ -23,6 +23,7 @@
 
 import logging
 import os
+from pathlib import Path
 from typing import Any, Dict, Optional
 
 from . import config     # reads app/.pyfun — single source of truth
@@ -54,6 +55,125 @@ def initialize() -> None:
     global _registry
     _registry = config.get_active_tools()
     logger.info(f"Tools loaded: {list(_registry.keys())}")
+    for tname, tcfg in _registry.items():
+        skill = tcfg.get("system_prompt_file", "")
+        if skill:
+            try:
+                _load_skill(skill)
+                logger.info(f"Tool '{tname}': skill '{skill}' loaded.")
+            except ValueError as e:
+                logger.warning(f"Tool '{tname}': {e}")
+
+
+# =============================================================================
+# Health — shared by the MCP tool and the REST gateway. Cheap, never raises, never blocks long.
+# =============================================================================
+
+async def health() -> Dict[str, Any]:
+    """Hub status incl. PostgreSQL awake-check (short ping), queue depth, providers, integrations."""
+    from . import pricing, discord_api, gsc
+    db = await db_sync.pg_status()
+    try:
+        queue = (await db_sync.persist_queue_stats()).get("queue_depth")
+    except Exception:
+        queue = None
+    degraded = db.get("bridge") == "active" and db.get("state") != "up"
+    return {
+        "status":        "degraded" if degraded else "ok",
+        "service":       "Universal MCP Hub",
+        "database":      db,
+        "persist_queue": queue,
+        "llm_providers":    providers.list_active_llm(),
+        "search_providers": providers.list_active_search(),
+        "pricing_ready":    pricing.is_ready(),
+        "stale_models":     pricing.check_models(),
+        "integrations":     {"discord": discord_api.is_ready(), "gsc": gsc.is_ready()},
+    }
+
+
+# =============================================================================
+# Skills — system prompts as plain Markdown files in app/skills/
+# .pyfun [TOOL.xyz]: system_prompt_file = "my_skill.md"  (combined with system_prompt if both set)
+# DATA only: the file is read as text and sent as system prompt. No code is ever executed
+# or imported from app/skills/ — dropping a file there cannot run anything.
+# =============================================================================
+_SKILLS_DIR = Path(__file__).resolve().parent / "skills"
+_SKILL_MAX_CHARS = 20000
+_skill_cache: Dict[str, str] = {}
+
+
+def _load_skill(name: str) -> str:
+    """Read app/skills/<name> (.md/.txt only, no path tricks). Cached until restart."""
+    name = (name or "").strip()
+    if not name:
+        return ""
+    if name in _skill_cache:
+        return _skill_cache[name]
+    path = (_SKILLS_DIR / name).resolve()
+    if _SKILLS_DIR not in path.parents or path.suffix.lower() not in (".md", ".txt"):
+        raise ValueError(f"system_prompt_file '{name}' must be a .md/.txt file inside app/skills/")
+    try:
+        text = path.read_text(encoding="utf-8").strip()[:_SKILL_MAX_CHARS]
+    except OSError:
+        raise ValueError(f"system_prompt_file '{name}' not found in app/skills/") from None
+    _skill_cache[name] = text
+    return text
+
+
+# =============================================================================
+# Discord post (hub → Discord). Inbound (/discord route, /ask) lives in app.py.
+# =============================================================================
+
+async def _run_discord(content: str, params: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Post `content` to Discord. mode: "auto" (default) | "webhook" | "bot".
+    A channel_id override is only accepted if listed in [DISCORD] DISCORD_ALLOWED_CHANNELS
+    (or equals DISCORD_DEFAULT_CHANNEL) — a hub client must not be able to make the bot
+    write into arbitrary channels.
+    """
+    from . import discord_api
+    cfg     = config.get_discord()
+    allowed = {c.strip() for c in str(cfg.get("DISCORD_ALLOWED_CHANNELS", "")).split(",") if c.strip()}
+    if cfg.get("DISCORD_DEFAULT_CHANNEL"):
+        allowed.add(str(cfg["DISCORD_DEFAULT_CHANNEL"]).strip())
+
+    channel = str(params.get("channel_id") or "").strip()
+    if channel and channel not in allowed:
+        return {"ok": False, "error": "channel_id not allowed — add it to DISCORD_ALLOWED_CHANNELS in .pyfun"}
+
+    mode = str(params.get("mode") or "auto").lower()
+    if mode == "webhook" or (mode == "auto" and not channel and discord_api.get_status()["webhook_set"]):
+        r = await discord_api.send_webhook(str(content))
+    else:
+        r = await discord_api.send_message(channel, str(content))
+    return {"ok": bool(r.get("ok")), "error": r.get("error"), "message_id": (r.get("data") or {}).get("id")}
+
+
+# =============================================================================
+# Response cache helper (opt-in per tool, backed by db_sync.tool_cache)
+# =============================================================================
+
+async def _cached(tool_name: str, key: str, tool_cfg: Dict, enabled: bool, call) -> str:
+    """Run `call()` (async callable); with cache = "true" serve/store via db_sync. Never breaks the call."""
+    if not enabled:
+        return await call()
+    try:
+        ttl = int(tool_cfg.get("cache_ttl_sec", "3600"))
+    except (TypeError, ValueError):
+        ttl = 3600
+    try:
+        hit = await db_sync.cache_read(tool_name, key, max_age_sec=ttl)
+        if hit is not None:
+            logger.info(f"Tool '{tool_name}': cache hit.")
+            return hit
+    except Exception as e:
+        logger.debug(f"Cache read skipped: {type(e).__name__}")
+    result = await call()
+    try:
+        await db_sync.cache_write(tool_name, key, result)
+    except Exception as e:
+        logger.debug(f"Cache write skipped: {type(e).__name__}")
+    return result
 
 
 # =============================================================================
@@ -62,29 +182,32 @@ def initialize() -> None:
 
 async def run(
     tool_name: str,
-    prompt: str,
+    prompt: Optional[str] = None,
     provider_name: Optional[str] = None,
     model: Optional[str] = None,
     max_tokens: int = 1024,
     max_results: int = 5,
+    **params: Any,
 ) -> str:
     """
     Execute a tool by name.
-    Reads tool config from registry, delegates to providers.py.
+    Reads tool config from registry, delegates to providers.py / db_sync.py.
     Applies system_prompt from .pyfun if defined.
 
     Args:
         tool_name:     Tool name as defined in .pyfun [TOOLS] (e.g. 'llm_complete').
-        prompt:        User input / query string.
+        prompt:        User input / query string. For db tools this is the SQL query.
         provider_name: Override provider. Defaults to tool's default_provider in .pyfun.
         model:         Override model. Defaults to provider's default_model in .pyfun.
         max_tokens:    Max tokens for LLM response. Default: 1024.
+        max_results:   Max results for search tools. Default: 5.
+        **params:      Ignored extras — keeps /api calls with unknown keys from crashing.
 
     Returns:
         Tool response as plain text string.
 
     Raises:
-        ValueError:   If tool_name is not found in registry.
+        ValueError:   If tool_name is not found in registry or prompt is missing.
         RuntimeError: If all providers fail (propagated from providers.py).
     """
     tool_cfg = _registry.get(tool_name)
@@ -94,25 +217,96 @@ async def run(
     provider_type    = tool_cfg.get("provider_type", "llm")
     default_provider = provider_name or tool_cfg.get("default_provider", "")
     system_prompt    = tool_cfg.get("system_prompt", "")
+    if tool_cfg.get("system_prompt_file"):
+        system_prompt = f"{system_prompt}\n\n{_load_skill(tool_cfg['system_prompt_file'])}".strip()
 
-    # Build full prompt — prepend system_prompt if defined in .pyfun
-    full_prompt = f"{system_prompt}\n\n{prompt}".strip() if system_prompt else prompt
+    # Skill DBs (app/skills_db.py): core rules first, relevant user skills last. Opt-in (costs tokens).
+    if provider_type == "llm":
+        from . import skills_db
+        scfg = config.get_skills()
+
+        def _on(tool_key: str, global_key: str) -> bool:
+            return str(tool_cfg.get(tool_key, scfg.get(global_key, "false"))).lower() == "true"
+
+        if skills_db.is_ready():
+            if _on("use_core", "SKILLS_INJECT_CORE") and skills_db.core_text():
+                system_prompt = f"{skills_db.core_text()}\n\n{system_prompt}".strip()
+            if _on("use_skills", "SKILLS_INJECT_RELEVANT"):
+                ctx = await skills_db.context_for(
+                    str(prompt or ""), int(scfg.get("SKILLS_TOP_K", "3")), int(scfg.get("SKILLS_MAX_CHARS", "3000")))
+                if ctx:
+                    system_prompt = f"{system_prompt}\n\n{ctx}".strip()
+
+    # prompt ist für llm/search/db Pflicht — sauberer 400er statt TypeError/500er
+    # persist ist die Ausnahme: ohne state_read_key braucht es einen prompt,
+    # mit state_read_key liest es stattdessen aus hub_state (Gedächtnis-Pattern).
+    needs_prompt = provider_type in ("llm", "search", "db", "discord") or \
+        (provider_type == "skills" and tool_cfg.get("skills_action") == "search")
+    if needs_prompt and (prompt is None or str(prompt).strip() == ""):
+        raise ValueError(
+            f"Tool '{tool_name}' requires a 'prompt' parameter (db: the SQL query, discord: the message)."
+        )
+    if provider_type == "persist" and not tool_cfg.get("state_read_key", "") \
+            and (prompt is None or str(prompt).strip() == ""):
+        raise ValueError(
+            "persist_result requires 'prompt' (or set state_read_key in .pyfun [TOOL.persist_result])."
+        )
+
+    # --- Skill DBs (read-only): catalog / search ---
+    if provider_type == "skills":
+        from . import skills_db
+        if tool_cfg.get("skills_action") == "catalog":
+            return await skills_db.catalog(scope=str(params.get("scope") or "all"), tag=str(params.get("tag") or ""))
+        return await skills_db.search(
+            query=str(prompt or ""), top_k=params.get("top_k", 3),
+            tag=str(params.get("tag") or ""), scope=str(params.get("scope") or "user"))
+
+    # --- Discord post ---
+    if provider_type == "discord":
+        return await _run_discord(prompt, params)
+
+    # --- Google Search Console (optional libs, see app/gsc.py) ---
+    if provider_type == "gsc":
+        from . import gsc
+        return await gsc.query(
+            property_url=str(params.get("property_url") or prompt or ""),
+            days_back=params.get("days_back", 30),
+            row_limit=params.get("row_limit", 10),
+            dimension=params.get("dimension", "query"),
+        )
+
+    # Opt-in response cache per tool: cache = "true" (+ cache_ttl_sec) in .pyfun [TOOL.xyz]
+    use_cache = str(tool_cfg.get("cache", "false")).lower() == "true"
 
     # --- LLM tools ---
+    # system_prompt goes out as a REAL system prompt (no longer glued into the user prompt).
+    # Only a model given (no provider) → provider is derived from .pyfun [MODELS].
     if provider_type == "llm":
-        return await providers.llm_complete(
-            prompt=full_prompt,
-            provider_name=default_provider,
-            model=model,
-            max_tokens=max_tokens,
+        prov = provider_name or providers.provider_for_model(model) or tool_cfg.get("default_provider", "")
+        return await _cached(
+            tool_name, f"{prov}|{model or ''}|{max_tokens}|{system_prompt}|{prompt}", tool_cfg, use_cache,
+            lambda: providers.llm_complete(
+                prompt=prompt,
+                provider_name=prov,
+                model=model,
+                max_tokens=max_tokens,
+                system=system_prompt or None,
+                tool_name=tool_name,
+            ),
         )
 
     # --- Search tools ---
+    # providers.search() ignores provider names that are not search providers
+    # (e.g. a GUI sending its LLM provider along).
     if provider_type == "search":
-        return await providers.search(
-            query=prompt,
-            provider_name=default_provider,
-            max_results=int(tool_cfg.get("default_results", "5")),
+        n_results = max_results or int(tool_cfg.get("default_results", "5"))
+        return await _cached(
+            tool_name, f"{default_provider}|{n_results}|{prompt}", tool_cfg, use_cache,
+            lambda: providers.search(
+                query=prompt,
+                provider_name=default_provider,
+                max_results=n_results,
+            ),
         )
 
     # --- DB tools (read-only, delegated to db_sync when ready) ---
@@ -120,14 +314,41 @@ async def run(
         sql = prompt  # prompt ist hier die SQL-Query
         return await db_sync.query(sql)
 
-    # in run() — neuer persist-Block:
+    # --- Persist tools (Gedächtnis-Orchestrierung: SQLite-Queue → PostgreSQL) ---
+    # NIEMALS direkt an PG schreiben — enqueue in die restart-safe Queue,
+    # dann EINEN best-effort Flush-Versuch. Ohne DATABASE_URL = status "queued",
+    # kein Crash. Der Background-Flusher (db_sync) retries später automatisch.
     if provider_type == "persist":
-    # hub_state lesen + an PSQL schicken via db_sync bridge
-        key   = tool_cfg.get("state_read_key", "")
-        table = tool_cfg.get("target_table", "hub_results")
+        key    = tool_cfg.get("state_read_key", "")
+        table  = tool_cfg.get("target_table", "hub_results")
+        source = str(params.get("source") or tool_name)
+        # score: optionaler Slot für den Bullshit-Filter (Nutzer-eigenes Scoring).
+        # Wird 1:1 durchgereicht — KEIN Tool hier interpretiert oder berechnet ihn.
+        try:
+            score = float(params["score"]) if params.get("score") is not None else None
+        except (TypeError, ValueError):
+            score = None
         data  = await db_sync.read(key) if key else {"prompt": prompt}
-        await db_sync.persist(table, data)
-        return f"Persisted to PostgreSQL table '{table}'."
+        depth = await db_sync.enqueue_persist(
+            table, payload=data, source=source, model=model or "", score=score,
+        )
+        # best effort — waits at most PG_REQUEST_WAIT_SEC; a sleeping Neon never blocks the request
+        flush = await db_sync.flush_persist_queue_bounded()
+        if flush.get("flushed", 0) > 0:
+            status, note = "persisted", "written to PostgreSQL"
+        else:
+            status = "queued"
+            note = {
+                "pg_slow":    "PostgreSQL is slow/waking up — stays queued (SQLite) and flushes in the background",
+                "pg_backoff": "PostgreSQL unreachable a moment ago — stays queued (SQLite), retried automatically",
+            }.get(flush.get("reason"), "restart-safe in SQLite — flushes to PostgreSQL when the bridge becomes active")
+        return {
+            "status":        status,
+            "target_table":  table,
+            "queue_depth":   depth,
+            "flushed":       flush.get("flushed", 0),
+            "note":          note,
+        }
 
     # --- Unknown provider type ---
     logger.warning(f"Tool '{tool_name}' has unknown provider_type '{provider_type}' — skipped.")

desktop_ui.py

@@ -0,0 +1,978 @@
+# =============================================================================
+# mcp_desktop.py
+# Universal MCP Desktop Client
+# Copyright 2026 - Volkan Kücükbudak
+# Apache License V. 2 + ESOL 1.1
+# Repo: https://github.com/VolkanSah/Universal-MCP-Hub-sandboxed
+# =============================================================================
+# USAGE:
+#   pip install PySide6 httpx Pillow PyPDF2 pandas openpyxl
+#   python mcp_desktop.py
+#
+# CONNECT:
+#   1. Enter HF Token + Hub URL in Settings tab → Save
+#   2. Go to Connect tab → Connect
+#   3. Use Chat tab — select Tool, Provider, Model, upload files
+# =============================================================================
+# 7 Bugs from Claude AI fixed by Human 14.03.2026 but amazing work from ClaudeAi
+
+import sys
+import json
+import asyncio
+import httpx
+import io
+import base64
+import zipfile
+from datetime import datetime
+from pathlib import Path
+
+from PySide6.QtWidgets import (
+    QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
+    QPushButton, QLineEdit, QTextEdit, QLabel, QTabWidget,
+    QStatusBar, QComboBox, QSpinBox, QFileDialog
+)
+from PySide6.QtCore import QThread, Signal, QObject
+
+# Optional file handling imports — graceful degradation if missing
+try:
+    from PIL import Image
+    HAS_PIL = True
+except ImportError:
+    HAS_PIL = False
+
+try:
+    import PyPDF2
+    HAS_PDF = True
+except ImportError:
+    HAS_PDF = False
+
+try:
+    import pandas as pd
+    HAS_PANDAS = True
+except ImportError:
+    HAS_PANDAS = False
+
+
+# =============================================================================
+# Local config — saved to ~/.mcp_desktop.json
+# =============================================================================
+
+CONFIG_PATH = Path(__file__).parent / "mcp_desktop.json"
+# old CONFIG_PATH = Path.home() / ".mcp_desktop.json"
+
+def load_config() -> dict:
+    """Load local config. Returns defaults if not found."""
+    if CONFIG_PATH.exists():
+        try:
+            return json.loads(CONFIG_PATH.read_text())
+        except Exception:
+            pass
+    return {
+        "hf_token":         "",
+        "hub_url":          "",
+        "default_provider": "",
+        "default_model":    "",
+        "default_tool":     "llm_complete",
+        "font_size":        14,
+        "chats":            {},   # chat_id → {"title": str, "messages": [...]}
+    }
+
+def save_config(cfg: dict) -> None:
+    """Save config to mcp_desktop.json."""
+    try:
+        CONFIG_PATH.write_text(json.dumps(cfg, indent=2))
+    except Exception as e:
+        print(f"[save_config] WARNING: Could not save config: {e}")
+
+
+# =============================================================================
+# File Handler — extracted from Streamlit app
+# Supports: images, text/code, PDF, CSV/XLSX, ZIP
+# =============================================================================
+
+def encode_image(image) -> str:
+    """Encode PIL image to base64 JPEG string."""
+    buffered = io.BytesIO()
+    image.save(buffered, format="JPEG")
+    return base64.b64encode(buffered.getvalue()).decode("utf-8")
+
+
+def process_file(file_path: str) -> dict:
+    """
+    Process uploaded file into text or image content.
+    Returns dict: {"type": "text"|"image"|"error", "content": ...}
+    Supports: jpg/png, txt/code, pdf, csv/xlsx, zip
+    """
+    path      = Path(file_path)
+    file_type = path.suffix.lower().lstrip(".")
+
+    # Images — requires Pillow
+    if file_type in ["jpg", "jpeg", "png"]:
+        if not HAS_PIL:
+            return {"type": "error", "content": "Pillow not installed — pip install Pillow"}
+        img = Image.open(file_path).convert("RGB")
+        return {"type": "image", "content": img, "b64": encode_image(img)}
+
+    # Text / code files
+    code_extensions = ["html", "css", "php", "js", "py", "java", "c", "cpp",
+                       "ts", "go", "rb", "rs", "sh", "sql", "json", "xml", "md"]
+    if file_type in ["txt"] + code_extensions:
+        try:
+            return {"type": "text", "content": path.read_text(encoding="utf-8")}
+        except Exception as e:
+            return {"type": "error", "content": str(e)}
+
+    # CSV / Excel — requires pandas
+    if file_type in ["csv", "xlsx"]:
+        if not HAS_PANDAS:
+            return {"type": "error", "content": "pandas not installed — pip install pandas openpyxl"}
+        try:
+            df = pd.read_csv(file_path) if file_type == "csv" else pd.read_excel(file_path)
+            return {"type": "text", "content": df.to_string()}
+        except Exception as e:
+            return {"type": "error", "content": str(e)}
+
+    # PDF — requires PyPDF2
+    if file_type == "pdf":
+        if not HAS_PDF:
+            return {"type": "error", "content": "PyPDF2 not installed — pip install PyPDF2"}
+        try:
+            reader  = PyPDF2.PdfReader(file_path)
+            content = "".join(
+                page.extract_text() for page in reader.pages if page.extract_text()
+            )
+            return {"type": "text", "content": content}
+        except Exception as e:
+            return {"type": "error", "content": str(e)}
+
+    # ZIP — recursive text extraction
+    if file_type == "zip":
+        try:
+            text_extensions = (
+                ".txt", ".csv", ".py", ".html", ".js", ".css", ".php",
+                ".json", ".xml", ".c", ".cpp", ".java", ".cs", ".rb",
+                ".go", ".ts", ".swift", ".kt", ".rs", ".sh", ".sql", ".md"
+            )
+            content = "ZIP Contents:\n"
+            with zipfile.ZipFile(file_path) as z:
+                for info in z.infolist():
+                    if info.is_dir():
+                        continue
+                    try:
+                        with z.open(info.filename) as f:
+                            if info.filename.lower().endswith(text_extensions):
+                                content += f"\n📄 {info.filename}:\n{f.read().decode('utf-8')}\n"
+                            else:
+                                try:
+                                    content += f"\n📄 {info.filename}:\n{f.read().decode('utf-8')}\n"
+                                except UnicodeDecodeError:
+                                    content += f"\n⚠️ Binary ignored: {info.filename}\n"
+                    except Exception as e:
+                        content += f"\n❌ Error in {info.filename}: {e}\n"
+            return {"type": "text", "content": content}
+        except Exception as e:
+            return {"type": "error", "content": str(e)}
+
+    return {"type": "error", "content": f"Unsupported format: .{file_type}"}
+
+
+# =============================================================================
+# Async Worker — all Hub HTTP communication
+# =============================================================================
+class AsyncWorker(QObject):
+    result  = Signal(str)
+    error   = Signal(str)
+    log     = Signal(str)
+    tools   = Signal(dict)
+    status  = Signal(str)
+
+    def __init__(self, hub_url: str, hf_token: str):
+        super().__init__()
+        self.hub_url = hub_url.rstrip("/")
+        self.headers = {"Authorization": f"Bearer {hf_token}"}
+
+    def _run(self, coro):
+        """Run coroutine in fresh event loop — thread safe."""
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(coro)
+        finally:
+            loop.close()
+
+    def health_check(self):
+        """GET / — returns uptime + status."""
+        async def _do():
+            try:
+                async with httpx.AsyncClient() as client:
+                    r    = await client.get(f"{self.hub_url}/", headers=self.headers, timeout=10)
+                    data = r.json()
+                    self.status.emit(f"● connected — uptime: {data.get('uptime_seconds', '?')}s")
+                    self.log.emit(f"[health] {json.dumps(data)}")
+            except Exception as e:
+                self.status.emit("✗ disconnected")
+                self.error.emit(f"Health check failed: {e}")
+        self._run(_do())
+
+    def fetch_tools(self):
+        """POST /api → list_active_tools — returns tools + providers + models."""
+        async def _do():
+            try:
+                async with httpx.AsyncClient() as client:
+                    r    = await client.post(
+                        f"{self.hub_url}/api",
+                        headers={**self.headers, "Content-Type": "application/json"},
+                        json={"tool": "list_active_tools", "params": {}},
+                        timeout=15,
+                    )
+                    data = r.json()
+                    self.tools.emit(data)
+                    self.log.emit(f"[tools] {json.dumps(data)}")
+            except Exception as e:
+                self.error.emit(f"Fetch tools failed: {e}")
+        self._run(_do())
+
+    def call_tool(self, tool_name: str, prompt: str, provider: str = None, model: str = None):
+        """
+        Generic tool call — POST /api with tool_name + params.
+        Handles all tools: llm_complete, summarize, translate, db_query, etc.
+        db_query uses 'sql' param instead of 'prompt'.
+        """
+        async def _do():
+            try:
+                # db_query needs 'sql' not 'prompt'
+                if tool_name == "db_query":
+                    params = {"sql": prompt}
+                else:
+                    params = {
+                        "prompt":       prompt,
+                        "provider_name": provider or "",
+                        "model":        model or "",
+                        "max_tokens":   1024,
+                    }
+
+                async with httpx.AsyncClient() as client:
+                    r = await client.post(
+                        f"{self.hub_url}/api",
+                        headers={**self.headers, "Content-Type": "application/json"},
+                        json={"tool": tool_name, "params": params},
+                        timeout=60,
+                    )
+                    data     = r.json()
+                    response = data.get("result", data.get("error", str(data)))
+                    if isinstance(response, (dict, list)):
+                        response = json.dumps(response, indent=2)
+                    self.result.emit(str(response))
+                    self.log.emit(f"[{tool_name}] prompt: {prompt[:60]}...")
+            except Exception as e:
+                self.error.emit(f"Tool call failed: {e}")
+        self._run(_do())
+
+
+# =============================================================================
+# Worker Thread
+# =============================================================================
+class WorkerThread(QThread):
+    def __init__(self, fn):
+        super().__init__()
+        self.fn = fn
+
+    def run(self):
+        self.fn()
+
+
+# =============================================================================
+# Main Window
+# =============================================================================
+class MCPDesktop(QMainWindow):
+
+    # GitHub dark theme
+    STYLE = """
+        QMainWindow, QWidget {{
+            background-color: #0d1117;
+            color: #e6edf3;
+            font-family: 'Consolas', monospace;
+            font-size: {font_size}px;
+        }}
+        QTabWidget::pane {{
+            border: 1px solid #21262d;
+            background: #0d1117;
+        }}
+        QTabBar::tab {{
+            background: #161b22;
+            color: #8b949e;
+            padding: 8px 16px;
+            border: 1px solid #21262d;
+            border-bottom: none;
+        }}
+        QTabBar::tab:selected {{
+            background: #0d1117;
+            color: #58a6ff;
+            border-bottom: 2px solid #58a6ff;
+        }}
+        QTabBar::tab:hover {{ color: #e6edf3; }}
+        QLineEdit {{
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 4px;
+            padding: 6px 10px;
+            color: #e6edf3;
+        }}
+        QLineEdit:focus {{ border-color: #58a6ff; }}
+        QTextEdit {{
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 4px;
+            padding: 8px;
+            color: #e6edf3;
+            font-family: 'Consolas', monospace;
+        }}
+        QPushButton {{
+            background: #21262d;
+            color: #e6edf3;
+            border: 1px solid #30363d;
+            border-radius: 4px;
+            padding: 6px 14px;
+            font-weight: bold;
+        }}
+        QPushButton:hover {{
+            background: #30363d;
+            border-color: #58a6ff;
+            color: #58a6ff;
+        }}
+        QPushButton:pressed {{ background: #161b22; }}
+        QPushButton#btn_connect {{
+            background: #238636; border-color: #2ea043; color: #fff;
+        }}
+        QPushButton#btn_connect:hover {{ background: #2ea043; }}
+        QPushButton#btn_send {{
+            background: #1f6feb; border-color: #388bfd; color: #fff; min-width: 80px;
+        }}
+        QPushButton#btn_send:hover {{ background: #388bfd; }}
+        QPushButton#btn_save {{
+            background: #6e40c9; border-color: #8957e5; color: #fff;
+        }}
+        QPushButton#btn_save:hover {{ background: #8957e5; }}
+        QPushButton#btn_new_chat {{
+            background: #0d1117; border-color: #238636; color: #3fb950; padding: 4px 10px;
+        }}
+        QPushButton#btn_new_chat:hover {{ background: #238636; color: #fff; }}
+        QComboBox {{
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 4px;
+            padding: 5px 8px;
+            color: #e6edf3;
+        }}
+        QComboBox QAbstractItemView {{
+            background: #161b22;
+            border: 1px solid #30363d;
+            color: #e6edf3;
+            selection-background-color: #21262d;
+        }}
+        QSpinBox {{
+            background: #161b22;
+            border: 1px solid #21262d;
+            border-radius: 4px;
+            padding: 4px 8px;
+            color: #e6edf3;
+        }}
+        QStatusBar {{
+            background: #161b22;
+            color: #8b949e;
+            border-top: 1px solid #21262d;
+            font-size: 12px;
+        }}
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.cfg              = load_config()
+        self._threads         = []     # list — prevents GC while running
+        self._file_cache      = None   # currently loaded file
+        self._current_chat_id = None
+        self._tools_loading   = False  # prevent duplicate tool fetches
+        self._last_models     = []     # Bug 3 fix: cached models for tool filter
+        self._last_llm_providers = []  # cached providers
+
+        self.setWindowTitle("Universal MCP Desktop")
+        self.setMinimumSize(1000, 720)
+        self._apply_style()
+        self._build_ui()
+        self._set_status("✗ not connected")
+        self._load_last_chat()
+
+    def _apply_style(self):
+        self.setStyleSheet(self.STYLE.format(font_size=self.cfg.get("font_size", 14)))
+
+    # =========================================================================
+    # UI Build
+    # =========================================================================
+    def _build_ui(self):
+        central = QWidget()
+        layout  = QVBoxLayout(central)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(0)
+
+        layout.addWidget(self._build_header())
+
+        self.tabs = QTabWidget()
+        self.tabs.addTab(self._tab_chat(),     "💬 Chat")
+        self.tabs.addTab(self._tab_tools(),    "🛠 Tools")
+        self.tabs.addTab(self._tab_connect(),  "🔌 Connect")
+        self.tabs.addTab(self._tab_settings(), "⚙ Settings")
+        self.tabs.addTab(self._tab_logs(),     "📋 Logs")
+        layout.addWidget(self.tabs)
+
+        self.setCentralWidget(central)
+        self.status_bar = QStatusBar()
+        self.setStatusBar(self.status_bar)
+
+    def _build_header(self) -> QWidget:
+        """Header bar: title | Tool | Provider | Model | status"""
+        header = QWidget()
+        header.setFixedHeight(48)
+        header.setStyleSheet("background: #161b22; border-bottom: 1px solid #21262d;")
+        row = QHBoxLayout(header)
+        row.setContentsMargins(16, 0, 16, 0)
+        row.setSpacing(8)
+
+        title = QLabel("⬡ Universal MCP Desktop")
+        title.setStyleSheet("color: #58a6ff; font-size: 15px; font-weight: bold;")
+        row.addWidget(title)
+        row.addSpacing(16)
+
+        # Tool selector — in header, always visible
+        row.addWidget(self._small_label("Tool:"))
+        self.tool_select = QComboBox()
+        self.tool_select.addItem("llm_complete")
+        self.tool_select.setMinimumWidth(130)
+        row.addWidget(self.tool_select)
+
+        # Provider selector
+        row.addWidget(self._small_label("Provider:"))
+        self.provider_select = QComboBox()
+        self.provider_select.addItem("default")
+        self.provider_select.setMinimumWidth(120)
+        row.addWidget(self.provider_select)
+
+        # Model selector
+        row.addWidget(self._small_label("Model:"))
+        self.model_select = QComboBox()
+        self.model_select.addItem("default")
+        self.model_select.setMinimumWidth(200)
+        row.addWidget(self.model_select)
+
+        row.addStretch()
+
+        self.status_label = QLabel("✗ not connected")
+        self.status_label.setStyleSheet("color: #f85149; font-size: 12px;")
+        row.addWidget(self.status_label)
+
+        return header
+
+    # =========================================================================
+    # Tab: Chat — multi-chat + file upload
+    # =========================================================================
+    def _tab_chat(self) -> QWidget:
+        tab    = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(12, 12, 12, 12)
+        layout.setSpacing(6)
+
+        # Chat selector row
+        chat_row = QHBoxLayout()
+        chat_row.addWidget(QLabel("Chat:"))
+        self.chat_select = QComboBox()
+        self.chat_select.setMinimumWidth(280)
+        self.chat_select.currentIndexChanged.connect(self._on_chat_selected)
+        chat_row.addWidget(self.chat_select)
+
+        new_btn = QPushButton("+ New")
+        new_btn.setObjectName("btn_new_chat")
+        new_btn.clicked.connect(self._new_chat)
+        chat_row.addWidget(new_btn)
+
+        del_btn = QPushButton("🗑")
+        del_btn.setToolTip("Delete current chat")
+        del_btn.clicked.connect(self._delete_chat)
+        chat_row.addWidget(del_btn)
+
+        chat_row.addStretch()
+        layout.addLayout(chat_row)
+
+        # Chat output
+        self.chat_output = QTextEdit()
+        self.chat_output.setReadOnly(True)
+        self.chat_output.setPlaceholderText(
+            "Connect in Connect tab first — Tool/Provider/Model selectable in header bar above"
+        )
+        layout.addWidget(self.chat_output)
+
+        # File label — shown when file attached, click to remove
+        self.file_label = QLabel("")
+        self.file_label.setStyleSheet(
+            "color: #3fb950; font-size: 11px; padding: 2px 6px;"
+            "background: #0d1117; border: 1px solid #238636; border-radius: 3px;"
+        )
+        self.file_label.hide()
+        self.file_label.mousePressEvent = lambda e: self._clear_file()
+        layout.addWidget(self.file_label)
+
+        # Input row
+        input_row = QHBoxLayout()
+
+        file_btn = QPushButton("📎")
+        file_btn.setToolTip("Attach file (image, PDF, text, ZIP, CSV...)")
+        file_btn.clicked.connect(self._attach_file)
+        input_row.addWidget(file_btn)
+
+        self.chat_input = QLineEdit()
+        self.chat_input.setPlaceholderText(
+            "Enter prompt — Tool/Provider/Model in header bar..."
+        )
+        self.chat_input.returnPressed.connect(self._send_chat)
+        input_row.addWidget(self.chat_input)
+
+        send_btn = QPushButton("Send ▶")
+        send_btn.setObjectName("btn_send")
+        send_btn.clicked.connect(self._send_chat)
+        input_row.addWidget(send_btn)
+        layout.addLayout(input_row)
+
+        return tab
+
+    # =========================================================================
+    # Tab: Tools
+    # =========================================================================
+    def _tab_tools(self) -> QWidget:
+        tab    = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(16, 16, 16, 16)
+        layout.setSpacing(8)
+
+        btn_row = QHBoxLayout()
+        refresh_btn = QPushButton("↻ Refresh Tools")
+        refresh_btn.clicked.connect(self._fetch_tools)
+        btn_row.addWidget(refresh_btn)
+        btn_row.addStretch()
+        layout.addLayout(btn_row)
+
+        self.tools_output = QTextEdit()
+        self.tools_output.setReadOnly(True)
+        self.tools_output.setPlaceholderText("Connect first, then refresh...")
+        layout.addWidget(self.tools_output)
+
+        return tab
+
+    # =========================================================================
+    # Tab: Connect — separate from Settings!
+    # =========================================================================
+    def _tab_connect(self) -> QWidget:
+        tab    = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(12)
+
+        layout.addWidget(self._section("Hub URL (edit in Settings tab)"))
+        self.connect_url_label = QLabel(self.cfg.get("hub_url", "— not configured —"))
+        self.connect_url_label.setStyleSheet("color: #58a6ff; padding: 6px 0;")
+        layout.addWidget(self.connect_url_label)
+
+        layout.addWidget(self._section("HF Token"))
+        token_ok = bool(self.cfg.get("hf_token"))
+        token_status = QLabel("✓ configured" if token_ok else "✗ not set — go to Settings")
+        token_status.setStyleSheet("color: #3fb950;" if token_ok else "color: #f85149;")
+        layout.addWidget(token_status)
+
+        btn_row = QHBoxLayout()
+        conn_btn = QPushButton("🔌 Connect")
+        conn_btn.setObjectName("btn_connect")
+        conn_btn.clicked.connect(self._connect)
+        btn_row.addWidget(conn_btn)
+
+        ping_btn = QPushButton("❤ Ping")
+        ping_btn.clicked.connect(self._health_check)
+        btn_row.addWidget(ping_btn)
+
+        refresh_btn = QPushButton("↻ Refresh Tools")
+        refresh_btn.clicked.connect(self._fetch_tools)
+        btn_row.addWidget(refresh_btn)
+
+        btn_row.addStretch()
+        layout.addLayout(btn_row)
+
+        layout.addStretch()
+
+        info = QTextEdit()
+        info.setReadOnly(True)
+        info.setMaximumHeight(80)
+        info.setPlainText(
+            "Connect = Health Check + auto-load Tools/Providers/Models into header dropdowns.\n"
+            "Token is only sent to your own Hub — never stored elsewhere."
+        )
+        info.setStyleSheet("color: #8b949e; background: #0d1117; border: none; font-size: 12px;")
+        layout.addWidget(info)
+
+        return tab
+
+    # =========================================================================
+    # Tab: Settings — ONLY config, no connect!
+    # =========================================================================
+    def _tab_settings(self) -> QWidget:
+        tab    = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(24, 24, 24, 24)
+        layout.setSpacing(12)
+
+        layout.addWidget(self._section("HuggingFace Token"))
+        self.token_input = QLineEdit(self.cfg.get("hf_token", ""))
+        self.token_input.setPlaceholderText("hf_...")
+        self.token_input.setEchoMode(QLineEdit.Password)
+        layout.addWidget(self.token_input)
+
+        layout.addWidget(self._section("Hub URL"))
+        self.url_input = QLineEdit(self.cfg.get("hub_url", ""))
+        self.url_input.setPlaceholderText("https://your-space-name.hf.space")
+        layout.addWidget(self.url_input)
+
+        layout.addWidget(self._section("Default Provider (optional)"))
+        self.default_provider_input = QLineEdit(self.cfg.get("default_provider", ""))
+        self.default_provider_input.setPlaceholderText("e.g. gemini — leave empty for Hub default")
+        layout.addWidget(self.default_provider_input)
+
+        layout.addWidget(self._section("Default Model (optional)"))
+        self.default_model_input = QLineEdit(self.cfg.get("default_model", ""))
+        self.default_model_input.setPlaceholderText("e.g. gemini-2.5-flash — leave empty for Hub default")
+        layout.addWidget(self.default_model_input)
+
+        layout.addWidget(self._section("Font Size"))
+        font_row = QHBoxLayout()
+        self.font_size_input = QSpinBox()
+        self.font_size_input.setRange(10, 24)
+        self.font_size_input.setValue(self.cfg.get("font_size", 14))
+        font_row.addWidget(self.font_size_input)
+        font_row.addStretch()
+        layout.addLayout(font_row)
+
+        layout.addStretch()
+
+        btn_row = QHBoxLayout()
+        save_btn = QPushButton("��� Save Settings")
+        save_btn.setObjectName("btn_save")
+        save_btn.clicked.connect(self._save_settings)
+        btn_row.addWidget(save_btn)
+        btn_row.addStretch()
+        layout.addLayout(btn_row)
+
+        info = QTextEdit()
+        info.setReadOnly(True)
+        info.setMaximumHeight(60)
+        info.setPlainText("Saved to ~/.mcp_desktop.json — go to Connect tab to connect.")
+        info.setStyleSheet("color: #8b949e; background: #0d1117; border: none; font-size: 12px;")
+        layout.addWidget(info)
+
+        return tab
+
+    # =========================================================================
+    # Tab: Logs
+    # =========================================================================
+    def _tab_logs(self) -> QWidget:
+        tab    = QWidget()
+        layout = QVBoxLayout(tab)
+        layout.setContentsMargins(16, 16, 16, 16)
+        layout.setSpacing(8)
+
+        btn_row = QHBoxLayout()
+        clear_btn = QPushButton("🗑 Clear")
+        clear_btn.clicked.connect(lambda: self.log_output.clear())
+        btn_row.addWidget(clear_btn)
+        btn_row.addStretch()
+        layout.addLayout(btn_row)
+
+        self.log_output = QTextEdit()
+        self.log_output.setReadOnly(True)
+        self.log_output.setPlaceholderText("All requests and responses appear here...")
+        layout.addWidget(self.log_output)
+
+        return tab
+
+    # =========================================================================
+    # Helper Widgets
+    # =========================================================================
+    def _section(self, text: str) -> QLabel:
+        label = QLabel(text)
+        label.setStyleSheet("color: #8b949e; font-size: 11px; margin-top: 8px;")
+        return label
+
+    def _small_label(self, text: str) -> QLabel:
+        label = QLabel(text)
+        label.setStyleSheet("color: #8b949e; font-size: 11px;")
+        return label
+
+    # =========================================================================
+    # Status + Log
+    # =========================================================================
+    def _set_status(self, text: str):
+        self.status_label.setText(text)
+        self.status_bar.showMessage(text)
+        connected = "connected" in text and "not" not in text
+        color = "#3fb950" if connected else "#f85149"
+        self.status_label.setStyleSheet(f"color: {color}; font-size: 12px;")
+
+    def _log(self, msg: str):
+        ts = datetime.now().strftime("%H:%M:%S")
+        self.log_output.append(f"[{ts}] {msg}")
+
+    def _make_worker(self) -> AsyncWorker:
+        return AsyncWorker(
+            hub_url=self.cfg.get("hub_url", ""),
+            hf_token=self.cfg.get("hf_token", ""),
+        )
+
+    def _run_in_thread(self, fn):
+        """Run in background QThread — list keeps all references alive until done."""
+        t = WorkerThread(fn)
+        def _cleanup():
+            try:
+                self._threads.remove(t)
+            except ValueError:
+                pass
+            t.deleteLater()
+        t.finished.connect(_cleanup)
+        t.start()
+        self._threads.append(t)
+
+    # =========================================================================
+    # Chat Management — multi-chat with timestamp IDs
+    # =========================================================================
+    def _new_chat(self):
+        """Create new chat session — ID = timestamp."""
+        chat_id = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        self.cfg.setdefault("chats", {})[chat_id] = {"title": f"Chat {chat_id}", "messages": []}
+        save_config(self.cfg)
+        self._refresh_chat_dropdown()
+        idx = self.chat_select.findText(chat_id)
+        if idx >= 0:
+            self.chat_select.setCurrentIndex(idx)
+        self._current_chat_id = chat_id
+        self.chat_output.clear()
+
+    def _delete_chat(self):
+        """Delete currently selected chat."""
+        chat_id = self.chat_select.currentText()
+        if chat_id and chat_id in self.cfg.get("chats", {}):
+            del self.cfg["chats"][chat_id]
+            save_config(self.cfg)
+            self._refresh_chat_dropdown()
+            self.chat_output.clear()
+
+    def _refresh_chat_dropdown(self):
+        """Rebuild dropdown — sorted newest first."""
+        self.chat_select.blockSignals(True)
+        self.chat_select.clear()
+        for chat_id in sorted(self.cfg.get("chats", {}).keys(), reverse=True):
+            self.chat_select.addItem(chat_id)
+        self.chat_select.blockSignals(False)
+        if self.chat_select.count() > 0:
+            self._on_chat_selected(0)
+
+    def _on_chat_selected(self, idx: int):
+        """Load selected chat into output."""
+        chat_id = self.chat_select.currentText()
+        if not chat_id:
+            return
+        self._current_chat_id = chat_id
+        self.chat_output.clear()
+        for msg in self.cfg.get("chats", {}).get(chat_id, {}).get("messages", []):
+            self.chat_output.append(msg)
+
+    def _load_last_chat(self):
+        """Load most recent chat on startup — create one if none exist."""
+        self._refresh_chat_dropdown()
+        if self.chat_select.count() > 0:
+            self.chat_select.setCurrentIndex(0)
+        else:
+            self._new_chat()
+
+    def _save_chat_message(self, msg: str):
+        """Persist message to current chat history."""
+        if not self._current_chat_id:
+            return
+        self.cfg.setdefault("chats", {}).setdefault(
+            self._current_chat_id, {"title": "", "messages": []}
+        )["messages"].append(msg)
+        save_config(self.cfg)
+
+    # =========================================================================
+    # File Attachment
+    # =========================================================================
+    def _attach_file(self):
+        """Open file dialog — process and cache file for next send."""
+        path, _ = QFileDialog.getOpenFileName(
+            self, "Attach File", "",
+            "Supported (*.jpg *.jpeg *.png *.txt *.py *.php *.js *.html *.css "
+            "*.pdf *.csv *.xlsx *.zip *.json *.xml *.md *.sql *.sh *.c *.cpp *.java);;"
+            "All files (*.*)"
+        )
+        if not path:
+            return
+
+        result = process_file(path)
+        if result["type"] == "error":
+            self._log(f"File error: {result['content']}")
+            return
+
+        self._file_cache        = result
+        self._file_cache["path"] = path
+        filename                = Path(path).name
+        self.file_label.setText(f"📎 {filename}  (click to remove)")
+        self.file_label.show()
+        self._log(f"[file] loaded: {filename} ({result['type']})")
+
+    def _clear_file(self):
+        """Remove attached file."""
+        self._file_cache = None
+        self.file_label.hide()
+
+    # =========================================================================
+    # Actions
+    # =========================================================================
+    def _save_settings(self):
+        """Save settings only — no connect action."""
+        self.cfg["hf_token"]         = self.token_input.text().strip()
+        self.cfg["hub_url"]          = self.url_input.text().strip()
+        self.cfg["default_provider"] = self.default_provider_input.text().strip()
+        self.cfg["default_model"]    = self.default_model_input.text().strip()
+        self.cfg["font_size"]        = self.font_size_input.value()
+        save_config(self.cfg)
+        self._apply_style()
+        self.connect_url_label.setText(self.cfg.get("hub_url", "— not configured —"))
+        self._log("Settings saved — go to Connect tab to connect.")
+
+    def _connect(self):
+        """Health check + auto-fetch tools on success."""
+        if not self.cfg.get("hf_token") or not self.cfg.get("hub_url"):
+            self._set_status("✗ configure in Settings first!")
+            return
+        self._set_status("… connecting")
+        self._log(f"Connecting to {self.cfg['hub_url']}...")
+        w = self._make_worker()
+        w.status.connect(self._set_status)
+        w.status.connect(lambda s: self._fetch_tools() if "● connected" in s else None)
+        w.error.connect(lambda e: self._log(f"ERROR: {e}"))
+        w.log.connect(self._log)
+        self._run_in_thread(w.health_check)
+
+    def _health_check(self):
+        """Ping Hub — update status."""
+        w = self._make_worker()
+        w.status.connect(self._set_status)
+        w.status.connect(lambda s: self._fetch_tools() if "● connected" in s else None)
+        w.error.connect(lambda e: self._log(f"ERROR: {e}"))
+        w.log.connect(self._log)
+        self._run_in_thread(w.health_check)
+
+    def _fetch_tools(self):
+        """Fetch tools + providers + models — skip if already loading."""
+        if self._tools_loading:
+            return
+        self._tools_loading = True
+        w = self._make_worker()
+        w.tools.connect(self._on_tools)
+        w.error.connect(lambda e: setattr(self, '_tools_loading', False) or self._log(f"ERROR: {e}"))
+        w.log.connect(self._log)
+        self._run_in_thread(w.fetch_tools)
+
+    def _on_tools(self, data: dict):
+        """Populate tool/provider/model dropdowns from Hub response."""
+        self._tools_loading = False
+        result = data.get("result", data)
+        self.tools_output.setPlainText(
+            json.dumps({"active_tools": result}, indent=2)
+            if isinstance(result, list)
+            else json.dumps(result, indent=2)
+        )
+
+        tools = result.get("active_tools", []) if isinstance(result, dict) else []
+        try:
+            self.tool_select.currentTextChanged.disconnect(self._populate_models_for_tool)
+        except RuntimeError:
+            pass
+        self.tool_select.clear()
+        for t in tools:
+            self.tool_select.addItem(t)
+        idx = self.tool_select.findText(self.cfg.get("default_tool", "llm_complete"))
+        if idx >= 0:
+            self.tool_select.setCurrentIndex(idx)
+
+        self.provider_select.clear()
+        self.provider_select.addItem("default")
+        for p in result.get("active_llm_providers", []) if isinstance(result, dict) else []:
+            self.provider_select.addItem(p)
+
+        self._last_models = result.get("available_models", []) if isinstance(result, dict) else []
+        self._last_llm_providers = result.get("active_llm_providers", []) if isinstance(result, dict) else []
+
+        self._populate_models_for_tool(self.tool_select.currentText())
+        self.tool_select.currentTextChanged.connect(self._populate_models_for_tool)
+
+        self._log(f"Tools loaded: {tools}")
+
+    _LLM_TOOLS = {"llm_complete", "code_review", "summarize", "translate"}
+
+    def _populate_models_for_tool(self, tool_name: str):
+        """Filter model dropdown based on selected tool — only LLM tools need models."""
+        self.model_select.clear()
+        self.model_select.addItem("default")
+        if tool_name in self._LLM_TOOLS:
+            for m in getattr(self, "_last_models", []):
+                self.model_select.addItem(m)
+
+    def _send_chat(self):
+        """Send prompt to Hub — uses Tool/Provider/Model from header dropdowns."""
+        prompt = self.chat_input.text().strip()
+        if not prompt:
+            return
+
+        tool_name = self.tool_select.currentText() or "llm_complete"
+        provider  = self.provider_select.currentText()
+        if provider == "default":
+            provider = self.cfg.get("default_provider") or None
+        model = self.model_select.currentText()
+        if model == "default":
+            model = self.cfg.get("default_model") or None
+
+        full_prompt = prompt
+        if self._file_cache:
+            if self._file_cache["type"] == "text":
+                full_prompt = f"{prompt}\n\n[File Content]\n{self._file_cache['content']}"
+            self._clear_file()
+
+        user_msg = f"\n▶ You [{tool_name}]: {prompt}"
+        self.chat_output.append(user_msg)
+        self._save_chat_message(user_msg)
+        self.chat_input.clear()
+        self._log(f"→ tool: {tool_name}, provider: {provider or 'default'}, model: {model or 'default'}")
+
+        w = self._make_worker()
+        def on_result(r):
+            msg = f"⬡ Hub: {r}\n"
+            self.chat_output.append(msg)
+            self._save_chat_message(msg)
+        w.result.connect(on_result)
+        w.error.connect(lambda e: self.chat_output.append(f"✗ Error: {e}\n"))
+        w.log.connect(self._log)
+        self._run_in_thread(lambda: w.call_tool(tool_name, full_prompt, provider, model))
+
+
+# =============================================================================
+# Entry Point
+# =============================================================================
+if __name__ == "__main__":
+    if sys.platform == "win32":
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+    app    = QApplication(sys.argv)
+    window = MCPDesktop()
+    window.show()
+    sys.exit(app.exec())

example-mcp___.env

@@ -1,30 +1,59 @@
 # ===========================================
-# MCP.env HUB CONFIGURATION
+# .env.example — Multi-LLM-API-Gateway
+# Copy this file to .env and fill in the values.
+# IMPORTANT: Never commit the .env file to version control.
+# ===========================================
+# ARCHITECTURE NOTE:
+#   The Guardian (main.py) is the ONLY process that reads this file.
+#   app/* modules NEVER touch .env — they get ENV-VAR NAMES via app/.pyfun
+#   and the values are read with os.getenv() inside the sandbox boundary.
+#
+#   No key set = provider skipped = tool not registered = NO CRASH.
 # ===========================================
 
-# App-Modus: 'mcp' oder 'app' (app ,modus for local)
-APP_MODE="mcp"
+# --- LLM Provider Keys ---
+# Which providers activate is defined in app/.pyfun [LLM_PROVIDERS].
+# A provider only registers when its ENV key here is set.
+
+# Anthropic (api.anthropic.com)
+ANTHROPIC_API_KEY=""
+
+# Google Gemini (generativelanguage.googleapis.com)
+GEMINI_API_KEY=""
+
+# OpenRouter (openrouter.ai) — free models available
+OPENROUTER_API_KEY=""
+
+# HuggingFace Inference API (api-inference.huggingface.co)
+HF_TOKEN=""
+
+# SmolLM2 custom Space (your own deployment)
+SMOLLM_API_KEY=""
+
+# --- Search Provider Keys ---
+# Activate search by setting at least one of these.
 
-# Transport: 'stdio' (lokal/Claude Desktop) oder 'sse' (HuggingFace/Remote)
-MCP_TRANSPORT="sse"
+# Brave Search (api.search.brave.com)
+BRAVE_API_KEY=""
 
-# Für SSE/HuggingFace Spaces (added by app/app.py)
-# PORT="7860"
-# HOST="0.0.0.0"
+# Tavily (api.tavily.com) — AI-optimized search
+TAVILY_API_KEY=""
 
-# Optional: Die App-URL für OpenRouter HTTP-Referer
+# --- App Identity (optional) ---
+# Used by OpenRouter HTTP-Referer header (rate limit attribution)
 APP_URL="https://huggingface.co/spaces/codey-lab/Universal-MCP-Hub"
 
-# .env.example
-# This file serves as a template for your .env file.
-# Copy this file to a new file named .env and fill in the values.
-# IMPORTANT: Never commit the .env file to version control.
+# --- Optional hub gate for /api, /crypto and /mcp (see app/auth.py) ---
+# Leave empty = hub is open (as before). Set a long random string to require it.
+# Clients send:  X-Hub-Token: <token>   or   Authorization: Bearer <token>
+# (the ENV var NAME is configured in app/.pyfun [HUB] HUB_AUTH_ENV)
+HUB_API_TOKEN=""
 
 # ===========================================
 # PyFundaments CORE CONFIGURATION
 # ===========================================
 
-# --- Database Connection ---
+# --- Database Connection (PostgreSQL) ---
 # The complete Data Source Name (DSN) for your PostgreSQL database.
 # This works for both local instances and cloud providers like Neon.tech.
 # Example for Neon: postgresql://user:password@host.eu-central-1.aws.neon.tech/neondb?sslmode=require
@@ -34,34 +63,30 @@ DATABASE_URL="your_database_dsn_here"
 
 # --- Application-Level Encryption Keys ---
 # These keys are used by the application itself to encrypt sensitive data
-# before it is written to the database. This provides an additional layer
-# of security for your data.
-# Comment out both lines if your app doesn't need encryption
+# before it is written to the database.
 # The master key must be a 256-bit key (32 bytes).
-#
 MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
-#
+
 # The salt is a unique, persistent value used with the master key.
 # It should also be a secure, random string.
-#
 PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"
-#
 
 # ===========================================
 # LOGGING CONFIGURATION (Optional)
 # ===========================================
 
-# PyFundaments Debug Mode (true/false)
-PYFUNDAMENTS_DEBUG="true"
+# PyFundaments Debug Mode (true = startup diagnostics: Python version,
+# sys.path, file checks). Only needed while developing — false for normal use.
+PYFUNDAMENTS_DEBUG="false"
 
 # Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
-LOG_LEVEL="DEBUG"
+# INFO is enough for daily operation; DEBUG only while hunting a bug.
+LOG_LEVEL="INFO"
 
-# Store logs in /tmp directory (cleared on restart)
+# Store logs in /tmp directory (cleared on restart, host-local only)
 LOG_TO_TMP="false"
 
-# Enable public logging (disable for production security)
-ENABLE_PUBLIC_LOGS="true"
-
-
-
+# Public logging — CAREFUL: stdout logs are PUBLICLY VISIBLE on HF Spaces
+# (Space -> Logs tab). Set to "false" for production. Only keep "true"
+# while actively debugging a deployment.
+ENABLE_PUBLIC_LOGS="false"

fundaments/access_control.py

@@ -43,12 +43,19 @@ class AccessControl:
     def __init__(self, user_id: Optional[int] = None):
         self.user_id = user_id
 
-    async def has_permission(self, permission_name: str) -> bool:
+    async def has_permission(self, permission_name: str, user_id: Optional[int] = None) -> bool:
         """
         Checks if the user has a specific permission.
         Uses the secure execute_secured_query function from the foundation.
+
+        Args:
+            permission_name: Name of the permission to check.
+            user_id:         Optional override — lets Security.check_permission()
+                             check ANY user without constructing a new instance.
+                             Falls back to the constructor user_id.
         """
-        if self.user_id is None:
+        effective_user_id = user_id if user_id is not None else self.user_id
+        if effective_user_id is None:
             return False
 
         # SQL Query Explanation:
@@ -66,7 +73,7 @@ class AccessControl:
         try:
             result = await db.execute_secured_query(
                 sql,
-                self.user_id,
+                effective_user_id,
                 permission_name,
                 fetch_method='fetchrow'
             )

fundaments/postgresql.py

@@ -4,6 +4,7 @@
 # Repo: https://github.com/VolkanSah/PyFundaments
 # fundaments/postgresql.py
 import os
+import asyncio
 import logging
 import asyncpg
 import ssl
@@ -122,8 +123,12 @@ async def init_db_pool(dsn_url: Optional[str] = None) -> Optional[asyncpg.Pool]:
             dsn=secured_dsn,
             min_size=1,
             max_size=10,
-            timeout=5,
+            # Neon scale-to-zero: suspended compute can need >5 s to wake up. This timeout also
+            # applies to every pool RECONNECT (was 5 → "Failed to restore the pool connection floor").
+            timeout=20,
             command_timeout=30,
+            # Neon suspends after ~5 min idle → drop idle connections ourselves before it kills them.
+            max_inactive_connection_lifetime=240,
             ssl=ssl_context
         )
         # Post-init checks
@@ -144,36 +149,69 @@ async def close_db_pool():
         _db_pool = None
         logger.info("Database pool closed successfully.")
 
+# Connection-level failures (dead/suspended Neon connection, wake-up timeout). Built defensively
+# so a missing attribute in some asyncpg version cannot break the import.
+_CONN_ERRORS = tuple(
+    e for e in (
+        getattr(asyncpg, "PostgresConnectionError", None),   # SQLSTATE class 08 (e.g. 08003, 08006)
+        getattr(asyncpg, "InterfaceError", None),            # "connection is closed" etc.
+        asyncio.TimeoutError,                                # connect/command timeout
+        OSError,                                             # socket-level (reset, refused, DNS)
+    ) if e
+)
+
+
 async def execute_secured_query(query: str, *params, fetch_method='fetch'):
     """
     Executes a parameterized query with integrated security checks.
+
+    Neon resilience: on a connection-level failure the query is retried ONCE with a fresh
+    connection (the pool discards dead ones). Safe by construction:
+      - failure while OBTAINING a connection (nothing was sent yet) → retried for every fetch_method
+      - failure DURING the statement → retried only for reads (fetch/fetchrow); an INSERT/UPDATE
+        ('execute') is NOT repeated — it may already have been committed.
     """
     global _db_pool
     if not _db_pool:
         raise RuntimeError("Database pool not initialized")
 
-    try:
-        async with _db_pool.acquire() as conn:
-            if fetch_method == 'fetch':
-                return await conn.fetch(query, *params)
-            elif fetch_method == 'fetchrow':
-                return await conn.fetchrow(query, *params)
-            elif fetch_method == 'execute':
-                return await conn.execute(query, *params)
+    for attempt in (1, 2):
+        in_statement = False
+        try:
+            async with _db_pool.acquire() as conn:
+                in_statement = True
+                if fetch_method == 'fetch':
+                    return await conn.fetch(query, *params)
+                elif fetch_method == 'fetchrow':
+                    return await conn.fetchrow(query, *params)
+                elif fetch_method == 'execute':
+                    return await conn.execute(query, *params)
+                else:
+                    raise ValueError("Invalid fetch_method")
+        except asyncpg.PostgresError as e:
+            sqlstate = getattr(e, 'sqlstate', None)
+            error_type = "Security violation" if sqlstate == '42501' else "Database error"
+
+            if os.getenv('APP_ENV') == 'production':
+                logger.error(f"{error_type} [Code: {sqlstate or '?'}]")
             else:
-                raise ValueError("Invalid fetch_method")
-    except asyncpg.PostgresError as e:
-        error_type = "Security violation" if getattr(e, 'sqlstate', None) == '42501' else "Database error"
-        
-        if os.getenv('APP_ENV') == 'production':
-            logger.error(f"{error_type} [Code: {getattr(e, 'sqlstate', '?')}]")
-        else:
-            logger.error(f"{error_type}: {e}")
-        
-        # Neon: Reconnect if connection terminated (optional)
-        if getattr(e, 'sqlstate', None) == '08006' and 'neon.tech' in (os.getenv("DATABASE_URL") or ''):
-            logger.warning("Neon.tech connection terminated. Restarting pool...")
-            await close_db_pool()
-            await init_db_pool(os.getenv("DATABASE_URL"))
-        
-        raise
+                logger.error(f"{error_type}: {e}")
+
+            # Neon: Reconnect if connection terminated (optional)
+            if sqlstate == '08006' and 'neon.tech' in (os.getenv("DATABASE_URL") or ''):
+                logger.warning("Neon.tech connection terminated. Restarting pool...")
+                await close_db_pool()
+                await init_db_pool(os.getenv("DATABASE_URL"))
+
+            is_conn_error = isinstance(e, _CONN_ERRORS) or str(sqlstate or '').startswith('08')
+            if attempt == 1 and is_conn_error and (not in_statement or fetch_method in ('fetch', 'fetchrow')):
+                logger.warning("Connection error — retrying query once.")
+                continue
+            raise
+        except _CONN_ERRORS as e:
+            # Not a PostgresError: timeout / socket / interface error
+            if attempt == 1 and (not in_statement or fetch_method in ('fetch', 'fetchrow')):
+                logger.warning(f"DB connection problem ({type(e).__name__}) — retrying query once.")
+                continue
+            logger.error(f"DB connection problem ({type(e).__name__}) — giving up.")
+            raise

fundaments/security.py

@@ -50,14 +50,17 @@ class Security:
     # Wenn der Dienst nicht initialisiert wurde (wie oben), würde dies einen AttributeError auslösen.
     async def user_login(self, username: str, password: str, request_data: dict) -> bool:
         logger.info(f"Attempting login for user: {username}")
-        if await self.user_handler.login(username, password, request_data):
-            return await self.user_handler.validate_session(request_data)
+        # UserHandler.login() is synchronous (SQLite) — no await.
+        # The old 'await' raised TypeError: bool can't be awaited.
+        if self.user_handler.login(username, password, request_data):
+            return self.user_handler.validate_session(request_data)
         return False
 
     # VORHER: Hier fehlt die Überprüfung, ob 'self.access_control' None ist.
     async def check_permission(self, user_id: int, permission_name: str) -> bool:
+        """Checks permission for ANY user_id (not just the constructor one)."""
         logger.debug(f"Checking permission '{permission_name}' for user ID {user_id}")
-        return await self.access_control.has_permission(user_id, permission_name)
+        return await self.access_control.has_permission(permission_name, user_id=user_id)
 
     # VORHER: Hier wird geprüft, ob 'self.encryption' None ist, was korrekt ist.
     def encrypt_data(self, data: str) -> Dict[str, str]:

main.py

@@ -78,8 +78,13 @@ async def initialize_fundaments() -> Dict[str, Any]:
     if database_url and database_url != "your_database_dsn_here":
         try:
             db_service = await init_db_pool(database_url)
-            fundaments["db"] = db_service
-            logger.info("Database service initialized.")
+            if db_service is not None:
+                fundaments["db"] = db_service
+                logger.info("Database service initialized.")
+            else:
+                # init_db_pool() returns None instead of raising on failure
+                logger.warning("Database pool could not be built, continuing without DB.")
+                fundaments["db"] = None
         except Exception as e:
             logger.warning(f"Database initialization failed, continuing without DB: {e}")
             fundaments["db"] = None
@@ -119,17 +124,20 @@ async def initialize_fundaments() -> Dict[str, Any]:
         fundaments["access_control"] = None
 
     # --- User Handler Initialization ---
-    # Only initialize if we have a database connection
-    if fundaments["db"] is not None:
-        try:
-            user_handler_service = UserHandler(fundaments["db"])
-            fundaments["user_handler"] = user_handler_service
-            logger.info("User Handler service initialized.")
-        except Exception as e:
-            logger.warning(f"User Handler initialization failed: {e}")
-            fundaments["user_handler"] = None
-    else:
-        logger.info("No database available, skipping User Handler initialization.")
+    # UserHandler is SQLite-based (own Database class, see user_handler.py)
+    # and does NOT use the asyncpg pool — wiring it with the Postgres pool
+    # was a bug (pool has no fetchone/execute-sync interface).
+    # SQLite path: SQLITE_PATH env or fallback next to app/ (HF Spaces: read-only FS
+    # may fail — caught below, app continues without user_handler).
+    try:
+        from fundaments.user_handler import Database as UserDB
+        user_db = UserDB()
+        user_db.setup_tables()
+        user_handler_service = UserHandler(user_db)
+        fundaments["user_handler"] = user_handler_service
+        logger.info("User Handler service initialized (SQLite store).")
+    except Exception as e:
+        logger.warning(f"User Handler initialization failed: {e}")
         fundaments["user_handler"] = None
 
     # --- Security Manager Initialization ---

requirements.txt

@@ -5,7 +5,8 @@ passlib
 cryptography
 
 # MCP Hub Dependencies (needed for app/mcp.py)
-fastmcp
+# Code imports mcp.server.fastmcp — the mcp SDK, NOT the fastmcp package.
+mcp>=1.10,<2
 httpx
 quart
 hypercorn
@@ -30,4 +31,7 @@ requests
 #PyNaCl
 
 # Alternative PostgreSQL driver (if not using asyncpg)
-#psycopg2-binary
+#psycopg2-binary
+# Optional — Google Search Console tool (app/gsc.py), nur nötig wenn GSC_ACTIVE = "true":
+# google-api-python-client
+# google-auth