voidcraft-world-bridge 0.1.0__py3-none-any.whl

voidcraft_world_bridge/__init__.py

@@ -0,0 +1,13 @@
+"""voidcraft-world-bridge: a loopback server that lets voidcraft.world reach your machine.
+
+It mounts plugins under `/plugin/<name>/` behind a Host + Origin allowlist, so a
+page on voidcraft.world can talk to something on this machine — a local language
+model, first — while a page anywhere else cannot.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("voidcraft-world-bridge")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"

voidcraft_world_bridge/builtins.py

@@ -0,0 +1,19 @@
+"""The plugins every bridge mounts without being told to.
+
+Today that is `local-llm`: the reason a stranger runs this bridge at all is to
+let voidcraft.world reach their own model, so it must work with zero config. A
+plugin directory configured under the same name is skipped, never mounted twice
+(`load_plugins`, `preloaded`).
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+from voidcraft_world_bridge.local_llm.plugin import PLUGIN_NAME as LOCAL_LLM, LocalLlmPlugin
+from voidcraft_world_bridge.plugins import PluginContext
+
+
+def builtin_plugins(context: PluginContext, *, agent_runtimes: Iterable[object] = ()) -> dict[str, object]:
+    """name → plugin for every built-in. `agent_runtimes` are handed to
+    `local-llm` (see `local_llm/agents.py`); a stock bridge registers none."""
+    return {LOCAL_LLM: LocalLlmPlugin(context, agent_runtimes=agent_runtimes)}

voidcraft_world_bridge/cli.py

@@ -0,0 +1,111 @@
+"""`voidcraft-world-bridge` — run the bridge in the foreground, or ask one how it is.
+
+    voidcraft-world-bridge              serve on 127.0.0.1:7682 until Ctrl-C
+    voidcraft-world-bridge status       is one running here, and what does it mount?
+    voidcraft-world-bridge --version
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+from voidcraft_world_bridge import __version__
+from voidcraft_world_bridge.builtins import LOCAL_LLM, builtin_plugins
+from voidcraft_world_bridge.plugins import PluginContext, discover_plugin_dirs, load_plugins
+from voidcraft_world_bridge.server import DEFAULT_PORT, LOOPBACK, NAME, build_handler, make_server
+
+PORT_ENV = "VOIDCRAFT_BRIDGE_PORT"
+
+
+def _log(message: str) -> None:
+    print(message, flush=True)
+
+
+def _default_port() -> int:
+    raw = os.environ.get(PORT_ENV)
+    try:
+        return int(raw) if raw else DEFAULT_PORT
+    except ValueError:
+        return DEFAULT_PORT
+
+
+def serve(port: int) -> int:
+    """Load plugins, bind loopback, serve until Ctrl-C. Exit code: 0 on Ctrl-C,
+    1 when the port is taken."""
+    context = PluginContext(status_port=port, log=_log)
+    plugins = load_plugins(discover_plugin_dirs(os.environ), context, preloaded=builtin_plugins(context))
+    try:
+        server = make_server(port, build_handler(plugins))
+    except OSError as err:
+        _log(f"{NAME}: cannot listen on {LOOPBACK}:{port} ({err.strerror or err}).")
+        _log(f"  Is another bridge already running? Check with: {NAME} status")
+        return 1
+    _log(f"{NAME} {__version__} — listening on http://{LOOPBACK}:{port}")
+    for name in plugins:
+        _log(f"  plugin: {name}  → http://{LOOPBACK}:{port}/plugin/{name}/…")
+    if LOCAL_LLM in plugins:
+        _log(f"  local model:  {describe_local_model(plugins[LOCAL_LLM])}")
+    _log("  Ctrl-C to stop")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        _log(f"\n{NAME}: stopped")
+    finally:
+        server.server_close()
+    return 0
+
+
+def describe_local_model(plugin) -> str:
+    """One line on what `local-llm` found, read through its own `/status` route,
+    so the banner and voidcraft.world can never disagree."""
+    _, status = plugin.handle_get("/status", {})
+    if not status.get("reachable"):
+        return ("none found — start Ollama or LM Studio (or llama-server), "
+                "or set VOIDCRAFT_LOCAL_LLM_URL; the bridge looks again on every request")
+    picked = status.get("picked_model") or "no chat model installed yet"
+    return f"{status.get('runtime_label')} at {status.get('runtime_url')} → {picked}"
+
+
+def fetch_snapshot(port: int, timeout: float = 2.0) -> dict | None:
+    """GET /snapshot from a bridge on this machine, or None if nothing answers."""
+    try:
+        with urllib.request.urlopen(f"http://{LOOPBACK}:{port}/snapshot", timeout=timeout) as response:
+            payload = json.loads(response.read())
+    except (urllib.error.URLError, OSError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def status(port: int) -> int:
+    """Print what a running bridge reports. Exit 1 when none answers."""
+    snapshot = fetch_snapshot(port)
+    if snapshot is None:
+        _log(f"{NAME}: nothing answering on {LOOPBACK}:{port}")
+        return 1
+    bridge = snapshot.get("bridge") if isinstance(snapshot.get("bridge"), dict) else {}
+    plugins = snapshot.get("plugins") if isinstance(snapshot.get("plugins"), dict) else {}
+    _log(f"{bridge.get('name', 'a bridge')} {bridge.get('version', '?')} — ONLINE on {LOOPBACK}:{port}")
+    _log(f"  plugins: {', '.join(sorted(plugins)) or '(none)'}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog=NAME, description="Let voidcraft.world reach your machine.")
+    parser.add_argument("--version", action="version", version=f"{NAME} {__version__}")
+    parser.add_argument("--port", type=int, default=_default_port(),
+                        help=f"loopback port (default {DEFAULT_PORT}, or ${PORT_ENV})")
+    commands = parser.add_subparsers(dest="command")
+    commands.add_parser("status", help="report on a bridge running here")
+    args = parser.parse_args(argv)
+    if args.command == "status":
+        return status(args.port)
+    return serve(args.port)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

voidcraft_world_bridge/guards.py

@@ -0,0 +1,131 @@
+"""Who may talk to the bridge: the Host (DNS-rebinding) and Origin guards.
+
+Every request a browser sends to a loopback server passes through these, and
+they are the whole reason a page on voidcraft.world may reach this machine while
+a page anywhere else may not. Pure functions over header values, so the tests
+need no socket.
+"""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import urlsplit
+
+# The single Origin allowlist for EVERY route: no Origin (curl, CLI, native
+# apps), a deployed VoidCraft origin, or ANY loopback origin — the dev SPA roams
+# ports (vite falls back to 5174+ when 5173 is taken; mkcert flips the scheme),
+# and a loopback page adds nothing an attacker doesn't already have.
+#
+# One guard, every route — read routes included. A host's read routes can leak
+# real content (a terminal pane's visible rows, a process's cwd), and wildcard
+# CORS on those means ANY page the user has open can read them cross-origin. The
+# browser's Private Network Access preflight is no backstop: it is answered
+# permissively for allowlisted origins, and Firefox/Safari don't implement it.
+ALLOWED_BROWSER_ORIGINS = frozenset({
+    "https://voidcraft.world",
+    "https://www.voidcraft.world",
+    "https://dev.voidcraft.world",
+})
+
+LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+# Extra Host values beyond loopback (`tailscale serve` remote access). The
+# second name is the one this bridge was born under, still honoured so an
+# existing setup keeps working.
+ALLOWED_HOSTS_ENV = "VOIDCRAFT_BRIDGE_ALLOWED_HOSTS"
+LEGACY_ALLOWED_HOSTS_ENV = "TERMINAL_BRIDGE_ALLOWED_HOSTS"
+
+
+def is_loopback_origin(origin: str) -> bool:
+    """True for http(s)://localhost|127.0.0.1|[::1] on any port; malformed → False."""
+    try:
+        parts = urlsplit(origin)
+        return parts.scheme in ("http", "https") and parts.hostname in LOOPBACK_HOSTS
+    except ValueError:
+        return False
+
+
+def origin_allowed(origin: str | None) -> bool:
+    """Whether a request carrying this Origin may be served at all.
+
+    `None` passes so that non-browser clients work: curl, CLI subcommands and
+    native apps send no Origin.
+
+    An absent Origin is NOT by itself proof of a non-browser client — see
+    `is_no_cors_browser_request`, which expensive routes use to tell the two
+    apart. This function is deliberately left permissive because routes that
+    are merely *readable* also serve legitimate no-Origin browser requests (a
+    plugin page loaded in an iframe, a hand-typed debug URL).
+    """
+    return origin is None or origin in ALLOWED_BROWSER_ORIGINS or is_loopback_origin(origin)
+
+
+def is_no_cors_browser_request(origin: str | None, sec_fetch_site: str | None) -> bool:
+    """True for a browser request that omitted Origin because it is `no-cors`.
+
+    `<img>`, `<script src>`, `<iframe src>` and `fetch(url, {mode:'no-cors'})`
+    all issue REAL cross-origin GETs while sending no Origin header — so the
+    "absent Origin means a native client" reading in `origin_allowed` does not
+    hold on its own. What does hold is that every browser making such a request
+    sends `Sec-Fetch-Site` (Chrome 76+, Firefox 90+, Safari 16.4+), and no
+    curl/URLSession/CLI caller sends it at all.
+
+    For routes where the request is EXPENSIVE rather than merely readable: the
+    attacker cannot read a no-cors response, so the risk there is not disclosure
+    but the work performed (a held thread, a subprocess per call).
+    """
+    return origin is None and sec_fetch_site is not None
+
+
+def host_header_hostname(host_header: str) -> str | None:
+    """The hostname from a Host header, port and IPv6 brackets stripped."""
+    try:
+        return urlsplit(f"//{host_header}").hostname
+    except ValueError:
+        return None
+
+
+def allowed_remote_hosts() -> frozenset[str]:
+    """Extra Host values accepted beyond loopback, from the environment.
+
+    Comma-separated in `VOIDCRAFT_BRIDGE_ALLOWED_HOSTS` (or the legacy
+    `TERMINAL_BRIDGE_ALLOWED_HOSTS`; both are read). A full URL is accepted and
+    reduced to its hostname, so `https://mymac.tailXXXX.ts.net` works.
+    """
+    raw = ",".join(os.environ.get(name, "") for name in (ALLOWED_HOSTS_ENV, LEGACY_ALLOWED_HOSTS_ENV))
+    hosts: set[str] = set()
+    for token in raw.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        if "//" in token:
+            token = token.split("//", 1)[1]
+        parsed = host_header_hostname(token)
+        if parsed:
+            hosts.add(parsed)
+    return frozenset(hosts)
+
+
+def host_allowed(host_header: str | None) -> bool:
+    """Whether the Host this request was addressed to may be served.
+
+    THE DNS-REBINDING GUARD, and the only defence against it — a loopback bind
+    is not one. An attacker page on `rebind.evil.com` (1s TTL, re-resolved to
+    127.0.0.1) makes the browser open a genuine same-origin connection to this
+    server, so every Origin/CORS check passes by construction: the attacker's
+    own hostname IS the origin. Only the Host tells us the request was
+    addressed to a name we do not answer to.
+
+    Absent Host passes (HTTP/1.0 clients omit it; a browser never does).
+
+    Non-loopback names must be listed explicitly in the env var. **A `*.ts.net`
+    suffix rule would be wrong here**: Tailscale *funnel* publishes
+    `<machine>.<tailnet>.ts.net` to the public internet, so an attacker with a
+    funneled node owns a perfectly real `.ts.net` name. Pin the machine.
+    """
+    if host_header is None:
+        return True
+    hostname = host_header_hostname(host_header)
+    if hostname is None:
+        return False
+    return hostname in LOOPBACK_HOSTS or hostname in allowed_remote_hosts()

voidcraft_world_bridge/local_llm/__init__.py

@@ -0,0 +1,4 @@
+"""Local intelligence: a job queue in front of a model server on this machine.
+
+Built into the bridge (`builtins.py`). Stdlib-only, like the rest of the package.
+"""

voidcraft_world_bridge/local_llm/agents.py

@@ -0,0 +1,31 @@
+"""Agent runtimes: a model reached some other way than a local server.
+
+A `/chat` body with an `agent: {runtime, …}` field goes to the agent runtime of
+that name instead of the local model, on its own queue and worker. The plugin
+ships with NONE; a host that embeds the bridge registers its own by passing
+`agent_runtimes=[…]` to `LocalLlmPlugin` (or `builtin_plugins`). A body naming a
+runtime that is not registered is a 400.
+
+An agent runtime is duck-typed:
+
+    name: str                                   # the `agent.runtime` value it answers to
+    default_model: str                          # the model a body that names none gets
+    model_error(model) -> str | None            # why a model is not one it takes
+    validate_agent(raw: dict) -> (dict | None, str | None)
+                                                # its own `agent` fields, cleaned, or why not
+    list_agents() -> list[dict]                 # rows for `GET /status?agents=1`
+    run(request: dict) -> dict                  # the chat result, or raise AgentRefused
+
+The plugin checks the shared contract before `validate_agent` runs: an agent
+takes exactly one system and one user message, and no tools.
+"""
+from __future__ import annotations
+
+
+class AgentRefused(Exception):
+    """The call must not run, or failed: `code` becomes the job's error code."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message

voidcraft_world_bridge/local_llm/jobs.py

@@ -0,0 +1,147 @@
+"""A bounded, single-worker job queue — why generation is a job and not a request.
+
+── WHY A JOB ─────────────────────────────────────────────────────────────────
+The host rule is "never block long": plugin handlers run on the bridge's
+request threads, which serve every other route too. One answer from a local
+model is 5–60 s, and the FIRST one after a cold start also pages the model in
+from disk. So `POST /chat` enqueues and returns 202 at once, and the page polls
+`GET /job`.
+
+── WHY ONE WORKER ────────────────────────────────────────────────────────────
+Two concurrent generations on one Mac do not finish sooner; they split the
+same memory bandwidth, and two DIFFERENT models loaded at once can exceed the
+GPU budget and push both onto the CPU. Serial is the fast order here.
+
+── WHY BOUNDED, TWICE ────────────────────────────────────────────────────────
+`MAX_PENDING` refuses new work while four jobs wait, because the fifth
+question would not start for minutes and the page that asked it has usually
+moved on. `MAX_KEPT` forgets the oldest FINISHED jobs, because nothing ever
+deletes a job otherwise and the bridge runs for weeks.
+"""
+from __future__ import annotations
+
+import queue
+import secrets
+import threading
+import time
+from typing import Callable
+
+MAX_PENDING = 4
+MAX_KEPT = 32
+
+QUEUED, RUNNING, DONE, FAILED = "queued", "running", "done", "failed"
+
+Runner = Callable[[dict], dict]
+"""Takes the job's `request`, returns the result dict or raises JobFailure."""
+
+
+class JobFailure(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+class QueueFull(Exception):
+    pass
+
+
+class JobStore:
+    def __init__(self, runner: Runner, *, clock: Callable[[], float] = time.time,
+                 start_worker: bool = True) -> None:
+        self._runner = runner
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._jobs: dict[str, dict] = {}
+        self._order: list[str] = []
+        self._pending: queue.Queue[str] = queue.Queue()
+        if start_worker:
+            threading.Thread(target=self._work_forever, name="local-llm-worker", daemon=True).start()
+
+    # -- public ---------------------------------------------------------------
+    def submit(self, request: dict) -> dict:
+        with self._lock:
+            waiting = sum(1 for j in self._jobs.values() if j["state"] == QUEUED)
+            if waiting >= MAX_PENDING:
+                raise QueueFull()
+            job_id = secrets.token_hex(8)
+            job = {"id": job_id, "state": QUEUED, "created_at": self._clock(),
+                   "started_at": None, "finished_at": None,
+                   "model": request.get("model"), "result": None, "error": None,
+                   "request": request}
+            self._jobs[job_id] = job
+            self._order.append(job_id)
+            self._forget_oldest_finished()
+            snapshot = self._public(job)
+        self._pending.put(job_id)
+        return snapshot
+
+    def get(self, job_id: str) -> dict | None:
+        with self._lock:
+            job = self._jobs.get(job_id)
+            return self._public(job) if job else None
+
+    def counts(self) -> dict:
+        with self._lock:
+            states = [j["state"] for j in self._jobs.values()]
+        return {"queued": states.count(QUEUED), "running": states.count(RUNNING)}
+
+    def run_next(self) -> bool:
+        """Run one queued job on THIS thread. The worker loop calls it; tests call it directly."""
+        try:
+            job_id = self._pending.get_nowait()
+        except queue.Empty:
+            return False
+        self._run(job_id)
+        return True
+
+    # -- internals ------------------------------------------------------------
+    def _work_forever(self) -> None:
+        while True:
+            job_id = self._pending.get()
+            self._run(job_id)
+
+    def _run(self, job_id: str) -> None:
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is None:
+                return
+            job["state"] = RUNNING
+            job["started_at"] = self._clock()
+            request = dict(job["request"])
+        try:
+            result = self._runner(request)
+            outcome = {"state": DONE, "result": result, "model": result.get("model") or request.get("model")}
+        except JobFailure as failure:
+            outcome = {"state": FAILED, "error": {"code": failure.code, "message": failure.message}}
+        except Exception as err:  # a runner bug must fail ONE job, never kill the worker
+            outcome = {"state": FAILED, "error": {"code": "internal", "message": str(err)[:300]}}
+        with self._lock:
+            job.update(outcome)
+            job["finished_at"] = self._clock()
+            job["request"] = {}  # the prompt is the user's content; do not keep it past the answer
+
+    def _forget_oldest_finished(self) -> None:
+        while len(self._order) > MAX_KEPT:
+            victim = next((jid for jid in self._order if self._jobs[jid]["state"] in (DONE, FAILED)), None)
+            if victim is None:
+                return
+            self._order.remove(victim)
+            del self._jobs[victim]
+
+    def _public(self, job: dict) -> dict:
+        started = job["started_at"]
+        finished = job["finished_at"]
+        now = self._clock()
+        elapsed = None
+        if started is not None:
+            elapsed = int(((finished if finished is not None else now) - started) * 1000)
+        return {
+            "id": job["id"],
+            "state": job["state"],
+            "model": job["model"],
+            "queued_ms": int(((started if started is not None else now) - job["created_at"]) * 1000),
+            "elapsed_ms": elapsed,
+            "result": job["result"],
+            "error": job["error"],
+        }

voidcraft_world_bridge/local_llm/models.py

@@ -0,0 +1,101 @@
+"""Which installed model answers when the caller does not name one.
+
+── NOBODY PICKS A MODEL TO START ─────────────────────────────────────────────
+A choice nearly everyone makes the same way is a default, not a question.
+Someone who has pulled `qwen3.6:35b-a3b` wants it used; asking them to also
+select it in VoidCraft is the question again. So the
+plugin picks the strongest installed model from an ordered list, `/status` says
+which one it picked, and a caller that names a model (Profile's override) wins.
+
+── WHY AN ORDERED LIST AND NOT "THE BIGGEST" ─────────────────────────────────
+Size is the wrong axis. A 35B MoE with 3B active parameters generates several
+times faster than a 27B dense model while being competitive on quality, and an
+embedding model can be the largest thing installed while being unable to chat
+at all. The order below is a judgement of quality per second on a desktop,
+not a size sort.
+
+── TWO NAMING SCHEMES ────────────────────────────────────────────────────────
+Ollama names a model `family:tag` (`qwen3.6:35b-a3b`). OpenAI-compatible servers
+use an id with no colon, often with an org prefix or a file name
+(`qwen/qwen3.6-35b-a3b`, `Qwen3.6-35B-A3B-Q4_K_M.gguf`). `matches` reads both, so
+one preference list serves every runtime.
+"""
+from __future__ import annotations
+
+PREFERENCE = (
+    "qwen3.6:35b-a3b",
+    "qwen3.8",
+    "qwen3.6:27b",
+    "qwen3.6",
+    "qwen3.5:35b-a3b",
+    "qwen3.5:27b",
+    "qwen3.5:9b",
+    "gemma4",
+    "qwen3.5:4b",
+    "qwen3",
+)
+"""Most-preferred first. An entry with a tag (`qwen3.6:35b-a3b`) matches that
+tag and its quantisation variants (`qwen3.6:35b-a3b-q8_0`); an entry without one
+(`qwen3.8`) matches any tag of that model."""
+
+_NOT_CHAT = ("embed", "bert", "rerank", "clip")
+"""Name/family fragments of models that cannot hold a conversation. The
+fallback below must never hand a question to an embedding model because it
+happened to be the only thing installed."""
+
+
+def is_chat_model(model: dict) -> bool:
+    name = str(model.get("name", "")).lower()
+    details = model.get("details") if isinstance(model.get("details"), dict) else {}
+    family = str(details.get("family", "")).lower()
+    families = " ".join(str(f).lower() for f in details.get("families") or [])
+    haystack = f"{name} {family} {families}"
+    return not any(fragment in haystack for fragment in _NOT_CHAT)
+
+
+def matches(preference: str, name: str) -> bool:
+    """Does installed `name` satisfy `preference`? See PREFERENCE for the rule,
+    and the module note for the two naming schemes."""
+    name = name.lower()
+    preference = preference.lower()
+    if ":" not in name:
+        # An OpenAI-style id: drop an `org/` prefix and a `.gguf` suffix, then
+        # read the preference's `:` as the `-` these ids use in its place.
+        name = name.rsplit("/", 1)[-1].removesuffix(".gguf")
+        flat = preference.replace(":", "-")
+        return name == flat or name.startswith(flat + "-")
+    if ":" in preference:
+        return name == preference or name.startswith(preference + "-")
+    return name.split(":", 1)[0] == preference
+
+
+def pick_model(installed: list[dict], pinned: str | None = None) -> str | None:
+    """The model a caller gets when it does not name one, or None.
+
+    `pinned` (the VOIDCRAFT_LOCAL_LLM_MODEL env var) wins when it is installed;
+    a pin naming a model that is NOT installed is ignored rather than obeyed,
+    because obeying it would fail every request with "model not found" while
+    a perfectly good model sits on disk.
+    """
+    names = [str(m.get("name", "")) for m in installed if m.get("name")]
+    if pinned and pinned in names:
+        return pinned
+    for preference in PREFERENCE:
+        for name in names:
+            if matches(preference, name):
+                return name
+    chat = sorted(str(m["name"]) for m in installed if m.get("name") and is_chat_model(m))
+    return chat[0] if chat else None
+
+
+def resolve_requested(requested: str | None, installed: list[dict], pinned: str | None) -> tuple[str | None, str | None]:
+    """(model, error_code). A named model must be installed — the plugin never pulls.
+
+    Pulling is a multi-gigabyte download; it belongs to the person at a
+    terminal (`ollama pull`), never to a page that happened to ask for a name.
+    """
+    names = {str(m.get("name", "")) for m in installed}
+    if requested:
+        return (requested, None) if requested in names else (None, "model_not_installed")
+    picked = pick_model(installed, pinned)
+    return (picked, None) if picked else (None, "no_model")