voidcraft-world-bridge 0.1.0__tar.gz

voidcraft_world_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoidCraft
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voidcraft_world_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: voidcraft-world-bridge
+Version: 0.1.0
+Summary: A loopback server that lets voidcraft.world reach your machine — starting with your own local LLM
+Keywords: local-llm,ollama,lm-studio,llama.cpp,voidcraft,bridge
+Author: VoidCraft
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10, <4
+Project-URL: Homepage, https://voidcraft.world
+Project-URL: Source, https://github.com/voidcraft-world/voidcraft-world-bridge
+Project-URL: Issues, https://github.com/voidcraft-world/voidcraft-world-bridge/issues
+Description-Content-Type: text/markdown
+
+# voidcraft-world-bridge
+
+A small loopback server that lets [voidcraft.world](https://voidcraft.world) talk to
+**your own local LLM**, so it can answer questions about your worlds or command a side in
+Arena World.
+
+```bash
+uvx voidcraft-world-bridge
+```
+
+That's the whole install. It finds your model server on its own and listens on
+`http://127.0.0.1:7682` until you press Ctrl-C:
+
+```
+voidcraft-world-bridge 0.1.0 — listening on http://127.0.0.1:7682
+  plugin: local-llm  → http://127.0.0.1:7682/plugin/local-llm/…
+  local model:  Ollama at http://127.0.0.1:11434 → qwen3.6:35b-a3b
+  Ctrl-C to stop
+```
+
+## Your model server
+
+Run any one of these and the bridge finds it, asking in this order:
+
+| Server | Where the bridge looks |
+|---|---|
+| [Ollama](https://ollama.com) | `http://127.0.0.1:11434` |
+| [LM Studio](https://lmstudio.ai) (start its local server) | `http://127.0.0.1:1234/v1` |
+| [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server` | `http://127.0.0.1:8080/v1` |
+
+Anything else that speaks the OpenAI API (vLLM, Jan, a custom port) works too. Point the
+bridge at it, and it asks only that server:
+
+```bash
+VOIDCRAFT_LOCAL_LLM_URL=http://127.0.0.1:8000/v1 uvx voidcraft-world-bridge
+```
+
+**Which model answers:** the strongest chat model you have, by a built-in preference list
+(Qwen 3.6 35B-A3B first). Embedding models are never picked. Pin one with
+`VOIDCRAFT_LOCAL_LLM_MODEL=<name>`. The bridge never downloads a model; install one with your
+server first (`ollama pull qwen3.5:9b` is a good small start).
+
+**What the OpenAI-compatible path cannot do:** set the context size per request. Load your model
+with enough context (16K or more) in the server itself.
+
+## Why it exists
+
+A web page cannot call `localhost` services directly: CORS and Chrome's Local Network
+Access stop it, on purpose. The bridge is the one door through, and it is narrow:
+
+- **Loopback only.** It binds `127.0.0.1`. There is no flag to bind anything wider.
+- **Origin allowlist.** Only `voidcraft.world` and pages served from your own machine
+  may call it. Any other site gets a `403`.
+- **DNS-rebinding guard.** A request addressed to any hostname other than `localhost` /
+  `127.0.0.1` / `[::1]` gets a `403`, even when the origin looks right.
+- **No shell, no files.** It routes chat requests to your model server and nothing else.
+- **Your prompts are not kept.** A request is dropped from memory once it is answered.
+- **Stdlib only.** Zero third-party dependencies.
+
+## The local-llm API
+
+Mounted at `/plugin/local-llm/`:
+
+| Route | Behaviour |
+|---|---|
+| `GET /status` | Which server answered (`runtime`, `runtime_label`, `runtime_url`), whether it is `reachable`, the installed **chat** models, and `picked_model`. Never an error when no server runs; `reachable: false` is a normal state. |
+| `POST /chat` | `{system, user}` or `{messages, tools?}`, plus `model?, max_tokens?, temperature?, format?, think?, num_ctx?, seed?` → **202** `{job_id}` at once. `400` on a bad body, `429` when 4 requests already wait. |
+| `GET /job?id=` | `queued` → `running` → `done` (`result.text`, `result.tool_calls`, token counts, `total_ms`) or `failed` (`error.code`: `runtime_down` · `runtime_error` · `no_model` · `model_not_installed`). |
+
+Generation is a job, not a request: one answer can take a minute, and one model generates one
+answer at a time — two at once would only split the same memory bandwidth.
+
+## Commands
+
+```bash
+voidcraft-world-bridge              # serve (foreground)
+voidcraft-world-bridge status       # is one running? what does it mount?
+voidcraft-world-bridge --version
+voidcraft-world-bridge --port 7700  # or VOIDCRAFT_BRIDGE_PORT=7700
+```
+
+## Plugins
+
+Everything the bridge can do is a plugin mounted at `/plugin/<name>/…`. `local-llm` is built
+in; add your own by pointing the bridge at a directory containing a `bridge_plugin.py`:
+
+```bash
+VOIDCRAFT_BRIDGE_PLUGINS=/path/to/my-plugin voidcraft-world-bridge
+```
+
+or list directories in `~/.config/voidcraft-world-bridge/plugins.json`:
+
+```json
+{ "version": 1, "plugins": ["/path/to/my-plugin"] }
+```
+
+A plugin module defines `PLUGIN_NAME` and `create_plugin(context)`, returning an object
+with `routes()`, `handle_get(subpath, query)` and `handle_post(subpath, query, body)`.
+Handlers return `(status, dict)` for JSON or `(status, bytes, content_type)` for a raw
+page. A plugin that fails to load is skipped, and a handler that raises becomes a `500`;
+a plugin can never take the bridge down. Full contract: `voidcraft_world_bridge/plugins.py`.
+
+## Remote access (optional)
+
+To reach the bridge through `tailscale serve`, name the machine explicitly:
+
+```bash
+VOIDCRAFT_BRIDGE_ALLOWED_HOSTS=mymac.tailXXXX.ts.net voidcraft-world-bridge
+```
+
+Never use `tailscale funnel` or a public tunnel: that publishes your bridge to the internet.

voidcraft_world_bridge-0.1.0/README.md

@@ -0,0 +1,111 @@
+# voidcraft-world-bridge
+
+A small loopback server that lets [voidcraft.world](https://voidcraft.world) talk to
+**your own local LLM**, so it can answer questions about your worlds or command a side in
+Arena World.
+
+```bash
+uvx voidcraft-world-bridge
+```
+
+That's the whole install. It finds your model server on its own and listens on
+`http://127.0.0.1:7682` until you press Ctrl-C:
+
+```
+voidcraft-world-bridge 0.1.0 — listening on http://127.0.0.1:7682
+  plugin: local-llm  → http://127.0.0.1:7682/plugin/local-llm/…
+  local model:  Ollama at http://127.0.0.1:11434 → qwen3.6:35b-a3b
+  Ctrl-C to stop
+```
+
+## Your model server
+
+Run any one of these and the bridge finds it, asking in this order:
+
+| Server | Where the bridge looks |
+|---|---|
+| [Ollama](https://ollama.com) | `http://127.0.0.1:11434` |
+| [LM Studio](https://lmstudio.ai) (start its local server) | `http://127.0.0.1:1234/v1` |
+| [llama.cpp](https://github.com/ggml-org/llama.cpp) `llama-server` | `http://127.0.0.1:8080/v1` |
+
+Anything else that speaks the OpenAI API (vLLM, Jan, a custom port) works too. Point the
+bridge at it, and it asks only that server:
+
+```bash
+VOIDCRAFT_LOCAL_LLM_URL=http://127.0.0.1:8000/v1 uvx voidcraft-world-bridge
+```
+
+**Which model answers:** the strongest chat model you have, by a built-in preference list
+(Qwen 3.6 35B-A3B first). Embedding models are never picked. Pin one with
+`VOIDCRAFT_LOCAL_LLM_MODEL=<name>`. The bridge never downloads a model; install one with your
+server first (`ollama pull qwen3.5:9b` is a good small start).
+
+**What the OpenAI-compatible path cannot do:** set the context size per request. Load your model
+with enough context (16K or more) in the server itself.
+
+## Why it exists
+
+A web page cannot call `localhost` services directly: CORS and Chrome's Local Network
+Access stop it, on purpose. The bridge is the one door through, and it is narrow:
+
+- **Loopback only.** It binds `127.0.0.1`. There is no flag to bind anything wider.
+- **Origin allowlist.** Only `voidcraft.world` and pages served from your own machine
+  may call it. Any other site gets a `403`.
+- **DNS-rebinding guard.** A request addressed to any hostname other than `localhost` /
+  `127.0.0.1` / `[::1]` gets a `403`, even when the origin looks right.
+- **No shell, no files.** It routes chat requests to your model server and nothing else.
+- **Your prompts are not kept.** A request is dropped from memory once it is answered.
+- **Stdlib only.** Zero third-party dependencies.
+
+## The local-llm API
+
+Mounted at `/plugin/local-llm/`:
+
+| Route | Behaviour |
+|---|---|
+| `GET /status` | Which server answered (`runtime`, `runtime_label`, `runtime_url`), whether it is `reachable`, the installed **chat** models, and `picked_model`. Never an error when no server runs; `reachable: false` is a normal state. |
+| `POST /chat` | `{system, user}` or `{messages, tools?}`, plus `model?, max_tokens?, temperature?, format?, think?, num_ctx?, seed?` → **202** `{job_id}` at once. `400` on a bad body, `429` when 4 requests already wait. |
+| `GET /job?id=` | `queued` → `running` → `done` (`result.text`, `result.tool_calls`, token counts, `total_ms`) or `failed` (`error.code`: `runtime_down` · `runtime_error` · `no_model` · `model_not_installed`). |
+
+Generation is a job, not a request: one answer can take a minute, and one model generates one
+answer at a time — two at once would only split the same memory bandwidth.
+
+## Commands
+
+```bash
+voidcraft-world-bridge              # serve (foreground)
+voidcraft-world-bridge status       # is one running? what does it mount?
+voidcraft-world-bridge --version
+voidcraft-world-bridge --port 7700  # or VOIDCRAFT_BRIDGE_PORT=7700
+```
+
+## Plugins
+
+Everything the bridge can do is a plugin mounted at `/plugin/<name>/…`. `local-llm` is built
+in; add your own by pointing the bridge at a directory containing a `bridge_plugin.py`:
+
+```bash
+VOIDCRAFT_BRIDGE_PLUGINS=/path/to/my-plugin voidcraft-world-bridge
+```
+
+or list directories in `~/.config/voidcraft-world-bridge/plugins.json`:
+
+```json
+{ "version": 1, "plugins": ["/path/to/my-plugin"] }
+```
+
+A plugin module defines `PLUGIN_NAME` and `create_plugin(context)`, returning an object
+with `routes()`, `handle_get(subpath, query)` and `handle_post(subpath, query, body)`.
+Handlers return `(status, dict)` for JSON or `(status, bytes, content_type)` for a raw
+page. A plugin that fails to load is skipped, and a handler that raises becomes a `500`;
+a plugin can never take the bridge down. Full contract: `voidcraft_world_bridge/plugins.py`.
+
+## Remote access (optional)
+
+To reach the bridge through `tailscale serve`, name the machine explicitly:
+
+```bash
+VOIDCRAFT_BRIDGE_ALLOWED_HOSTS=mymac.tailXXXX.ts.net voidcraft-world-bridge
+```
+
+Never use `tailscale funnel` or a public tunnel: that publishes your bridge to the internet.

voidcraft_world_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "voidcraft-world-bridge"
+version = "0.1.0"
+description = "A loopback server that lets voidcraft.world reach your machine — starting with your own local LLM"
+requires-python = ">=3.10,<4"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "local-llm",
+    "ollama",
+    "lm-studio",
+    "llama.cpp",
+    "voidcraft",
+    "bridge",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[[project.authors]]
+name = "VoidCraft"
+
+[project.urls]
+Homepage = "https://voidcraft.world"
+Source = "https://github.com/voidcraft-world/voidcraft-world-bridge"
+Issues = "https://github.com/voidcraft-world/voidcraft-world-bridge/issues"
+
+[project.scripts]
+voidcraft-world-bridge = "voidcraft_world_bridge.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=7.4.0,<8"]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"

voidcraft_world_bridge-0.1.0/pyproject.toml.orig

@@ -0,0 +1,45 @@
+[project]
+name = "voidcraft-world-bridge"
+version = "0.1.0"
+description = "A loopback server that lets voidcraft.world reach your machine — starting with your own local LLM"
+requires-python = ">=3.10,<4"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "VoidCraft" }]
+keywords = ["local-llm", "ollama", "lm-studio", "llama.cpp", "voidcraft", "bridge"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# Stdlib only, on purpose — see voidcraft_world_bridge/server.py.
+dependencies = []
+
+[project.urls]
+Homepage = "https://voidcraft.world"
+Source = "https://github.com/voidcraft-world/voidcraft-world-bridge"
+Issues = "https://github.com/voidcraft-world/voidcraft-world-bridge/issues"
+
+[project.scripts]
+voidcraft-world-bridge = "voidcraft_world_bridge.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.4.0,<8",
+]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.uv.build-backend]
+# voidcraft_world_bridge/ lives at the project root (flat layout), not under src/
+module-root = ""
+
+[build-system]
+requires = ["uv_build>=0.11.26,<0.12.0"]
+build-backend = "uv_build"

voidcraft_world_bridge-0.1.0/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-0.1.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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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