frutebox-node 0.1.0__py3-none-any.whl

frutebox/engine_guard.py

@@ -0,0 +1,718 @@
+"""The node's ENGINE GUARD — the single chokepoint between an inbound job and the
+model engine running on somebody's real machine.
+
+Why this exists
+---------------
+A provider node is an ordinary laptop, desktop or server owned by a volunteer or a
+customer. It accepts work from a gateway on behalf of *any* signed-up user. The job
+frame is therefore fully attacker-controlled data: model name, message list, tool
+schemas, generation flags. Before this module, that data was copied more or less
+verbatim into an HTTP request against a local engine daemon (Ollama / llama.cpp) that
+has **no authentication at all** and a full model-management API.
+
+Everything a job can influence now passes through here first.
+
+WHAT IS CONTAINED (enforced by this module + its callers)
+---------------------------------------------------------
+* **Engine surface.** Only the chat/generate/embed endpoints are reachable. The
+  model-management endpoints (``/api/pull``, ``/api/create``, ``/api/delete``,
+  ``/api/copy``, ``/api/push``, ``/api/blobs``) and llama.cpp's ``/slots``
+  (prompt-cache save/restore to disk) are refused *by path* — no job-handling code
+  can construct a URL for them, and a future caller that tries gets an exception
+  rather than a silent request.
+* **Model choice.** A job may only ask for a model the node explicitly advertises.
+  Anything else is rejected with an error the gateway can re-plan on, instead of
+  being handed to an engine that would go and *download* it.
+* **Message shape.** Only ``role``/``content``/``name``/``tool_call_id`` (plus
+  sanitised assistant ``tool_calls``) survive. Unknown fields are dropped — this is
+  what stops Ollama-specific field injection such as ``images``, and any future
+  field the engine learns to honour. Non-text content parts are flattened to text.
+* **Prompt size.** Bounded well below the 8 MB WebSocket frame limit — and the bound
+  counts *everything that leaves for the engine*, not just ``content``:
+  ``tool_calls[].function.arguments`` (itself truncated), ``name`` and
+  ``tool_call_id`` all count, because each of them was a way past the cap.
+* **Output modality.** A node only generates what it advertises
+  (``output_modalities``). The job frame names a modality; ``provider.py`` refuses one
+  this machine never offered, instead of loading SDXL on a text-only laptop.
+* **Tool schemas.** Bounded in count, nesting depth and serialised size; function
+  names must match a strict charset; every other key is dropped before the schema
+  reaches a chat template (llama.cpp runs with ``--jinja``).
+* **Tool EXECUTION.** Never happens on an untrusted node — see
+  ``assert_tool_execution_allowed``. Off by default even on a trusted one.
+* **Generation budget.** Explicit ``num_ctx``/``num_predict`` (Ollama sent none at
+  all before, so generation ran until the context filled) and a hard byte ceiling on
+  accumulated output that applies whatever the engine does with those hints.
+* **Engine location.** The engine must be on loopback. A misconfigured or hostile
+  ``OLLAMA_HOST``/``STEVAI_LLAMACPP_HOST`` cannot turn the node into a proxy that
+  posts user prompts to a remote host.
+* **Environment.** Helpers here build a MINIMAL environment for any child process
+  the node starts, so cloud credentials sitting in the owner's shell
+  (``AWS_*``, ``GOOGLE_APPLICATION_CREDENTIALS``, ``GITHUB_TOKEN``, …) are not
+  inherited by the engine or by anything parsing untrusted bytes.
+* **Node-private directories.** Model store and scratch space live under the node's
+  own directory (``$STEVAI_WORKSPACE`` when the supervisor provides one — this is
+  its first real consumer), not the global temp dir and not the owner's personal
+  ``~/.ollama``.
+
+WHAT IS **NOT** CONTAINED (read this before claiming "sandbox")
+---------------------------------------------------------------
+This is defence in depth at the *process* level. It is NOT a VM and NOT an OS
+sandbox. Specifically, still true after this module:
+
+* The node process and the engine daemon run **unconfined as the logged-in user**.
+  No namespaces, no seccomp, no chroot, no cgroups, no rlimits. A remote-code-
+  execution bug in the engine, in torch, or in a media codec gives the attacker the
+  user's account — this module only narrows the *inputs* that reach those parsers.
+* We do not start or supervise the engine daemon on most installs; a shell script
+  or Electron does. If that daemon was started by hand with the owner's environment
+  and their personal model store, the posture helpers here were never applied.
+  ``minimal_env()`` only protects children **we** spawn.
+* Nothing here verifies the engine BINARY. An unverified download is still an
+  unverified download; guarding its inputs does not make it trustworthy.
+* Memory, CPU share and disk are not capped by the OS. Concurrency and wall-clock
+  limits (``provider.py``) bound how much work a job can start, not how much RAM a
+  single model load takes.
+* A node that pulls a model at install time still egresses to the model registry.
+* On the desktop app the node still runs inside the Electron main process, so a
+  job-handling bug remains an app-level compromise, not just a job failure.
+
+Real containment for sensitive work is a *placement* decision (operator-run sealed
+Linux nodes), not something a consumer machine can honestly claim.
+"""
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import re
+import stat
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+from urllib.parse import urlsplit
+
+import httpx
+
+from .config import CONFIG
+from .envvars import env as envvar
+from .envvars import config_dir
+
+
+class EngineGuardError(RuntimeError):
+    """A job asked the engine for something this node will not do.
+
+    Raised (never swallowed) so the node reports an error frame and the gateway
+    re-plans, instead of the request quietly happening anyway.
+    """
+
+
+# --------------------------------------------------------------------------
+# 1. Engine endpoint allowlist
+# --------------------------------------------------------------------------
+# Inference endpoints. This is the whole reachable surface for job-handling code.
+CHAT_OLLAMA = "/api/chat"
+GENERATE_OLLAMA = "/api/generate"
+EMBED_OLLAMA = "/api/embed"
+CHAT_OPENAI = "/v1/chat/completions"
+COMPLETIONS_OPENAI = "/v1/completions"
+EMBEDDINGS_OPENAI = "/v1/embeddings"
+
+ALLOWED_ENDPOINTS = frozenset({
+    CHAT_OLLAMA, GENERATE_OLLAMA, EMBED_OLLAMA,
+    "/api/embeddings",              # Ollama's older embedding path
+    CHAT_OPENAI, COMPLETIONS_OPENAI, EMBEDDINGS_OPENAI,
+})
+
+# Model-management and engine-admin endpoints. Listed EXPLICITLY (rather than relying
+# on "not in the allowlist") so the ban is testable and so widening ALLOWED_ENDPOINTS
+# by accident cannot re-open them. `/api/pull` is the dangerous one: an engine with no
+# auth will happily download and install any model a caller names.
+FORBIDDEN_ENDPOINTS = frozenset({
+    "/api/pull", "/api/push", "/api/create", "/api/delete", "/api/copy", "/api/blobs",
+    "/api/show", "/api/tags", "/api/ps", "/api/version",
+    "/v1/models",
+    # llama.cpp server admin surface. /slots can persist and restore prompt caches to
+    # disk paths the caller chooses; /props leaks the host's serving config.
+    "/slots", "/props", "/completion", "/infill", "/tokenize", "/detokenize",
+    "/lora-adapters", "/metrics", "/health",
+})
+
+_TRUSTED_LABELS = ("owned", "trusted")
+
+
+def _normalise_base(base: str) -> str:
+    """Scheme + host + port of the engine, with any path/query the caller smuggled in
+    thrown away, and the host required to be loopback."""
+    raw = (base or "").strip()
+    if not raw:
+        raise EngineGuardError("no engine host configured")
+    if "://" not in raw:
+        raw = f"http://{raw}"          # Ollama's "127.0.0.1:11434" convention
+    parts = urlsplit(raw)
+    if parts.scheme not in ("http", "https"):
+        raise EngineGuardError(f"engine host must be http(s), got {parts.scheme!r}")
+    host = connect_host(parts.hostname or "")
+    if not host:
+        raise EngineGuardError("engine host has no hostname")
+    if not CONFIG.node_engine_allow_remote and not _is_loopback(host):
+        raise EngineGuardError(
+            f"engine host {host!r} is not loopback — a node must not send prompts off-box. "
+            "Set STEVAI_NODE_ENGINE_ALLOW_REMOTE=1 only if the operator runs the engine "
+            "on a private link they control.")
+    port = f":{parts.port}" if parts.port else ""
+    # `parts.hostname` strips the brackets off an IPv6 literal, so they have to go back
+    # on — "http://::1:8080/api/chat" is not a parseable URL and every job would fail
+    # transport-side on a node whose engine is addressed as [::1].
+    if ":" in host:
+        host = f"[{host}]"
+    return f"{parts.scheme}://{host}{port}"
+
+
+#: A BIND address meaning "every interface". As a CONNECT address it is not a destination —
+#: it means "this host", i.e. loopback. Containers routinely set OLLAMA_HOST=0.0.0.0 so the
+#: engine listens broadly, and the node then read that same value back as the address to dial.
+#: Verified live 2026-08-21: the warm node registered, was placed, and every job died with
+#: "engine host '0.0.0.0' is not loopback" — the guard was right, the address was wrong.
+_ANY_ADDRESS = {"0.0.0.0", "::", "[::]"}
+
+
+def connect_host(host: str) -> str:
+    """The address to DIAL for an engine configured with `host`.
+
+    A wildcard bind address is rewritten to loopback. This is a translation, not a
+    relaxation: 0.0.0.0 was never a reachable destination, and the alternative — telling
+    operators to set a second variable to the same engine on the same box — is a footgun that
+    ends with someone setting ALLOW_REMOTE to silence it.
+    """
+    h = (host or "").strip()
+    return "127.0.0.1" if h in _ANY_ADDRESS else h
+
+
+def _is_loopback(host: str) -> bool:
+    if host.lower() in ("localhost", "localhost.localdomain"):
+        return True
+    try:
+        return ipaddress.ip_address(host.strip("[]")).is_loopback
+    except ValueError:
+        return False
+
+
+def engine_url(base: str, path: str) -> str:
+    """Build the ONE URL a caller is allowed to hit, or raise.
+
+    Rejects traversal, absolute URLs, protocol-relative paths, query strings and any
+    endpoint outside ``ALLOWED_ENDPOINTS``.
+    """
+    p = (path or "").strip()
+    if not p.startswith("/") or p.startswith("//") or "://" in p or ".." in p:
+        raise EngineGuardError(f"illegal engine path {path!r}")
+    if "?" in p or "#" in p:
+        raise EngineGuardError(f"engine path may not carry a query or fragment: {path!r}")
+    canonical = p.rstrip("/") or "/"
+    if canonical in FORBIDDEN_ENDPOINTS:
+        raise EngineGuardError(
+            f"engine endpoint {canonical!r} is model management / admin and is never "
+            "reachable from job handling")
+    if canonical not in ALLOWED_ENDPOINTS:
+        raise EngineGuardError(f"engine endpoint {canonical!r} is not on the node's allowlist")
+    return f"{_normalise_base(base)}{canonical}"
+
+
+# --------------------------------------------------------------------------
+# 2. Model allowlist — a job may only name a model this node actually advertises
+# --------------------------------------------------------------------------
+_allowed_models: "Optional[set]" = None
+
+
+def arm_models(models: Iterable[str]) -> None:
+    """Pin the models this node will ask its engine for.
+
+    Called by the provider agent at startup with what it advertises to the directory.
+    Both the catalog id and the concrete engine tag are accepted, because the gateway
+    may legitimately send either. An empty/blank list leaves the guard DISARMED
+    (permissive) — that is the gateway/test context, where there is no node to protect.
+
+    That permissive default is load-bearing for the gateway and a foot-gun on a node:
+    a set-but-EMPTY ``$STEVAI_OLLAMA_MODEL`` used to reach here as ``[""]`` and turn
+    ``check_model`` into a process-wide pass-through. ``provider.py`` therefore checks
+    ``models_armed()`` after calling this and REFUSES TO START if it is False. Any new
+    caller that guards a real engine must do the same — do not assume arming worked.
+    """
+    global _allowed_models
+    from .manifest import OLLAMA_TAGS
+
+    vals: set = set()
+    for m in models or []:
+        name = str(m or "").strip()
+        if not name:
+            continue
+        vals.add(name)
+        vals.add(OLLAMA_TAGS.get(name, name))
+    _allowed_models = vals or None
+
+
+def disarm_models() -> None:
+    """Drop the allowlist (tests, and the gateway-side import of `inference`)."""
+    global _allowed_models
+    _allowed_models = None
+
+
+def models_armed() -> bool:
+    return _allowed_models is not None
+
+
+def allowed_models() -> List[str]:
+    return sorted(_allowed_models or ())
+
+
+def check_model(requested: str, resolved: str) -> str:
+    """Return `resolved` if this node serves it, else raise.
+
+    Rejecting is the point: an unguarded engine treats "model I don't have" as
+    "model I should go and fetch", which is remote-controlled disk + bandwidth use
+    on somebody else's machine.
+    """
+    if _allowed_models is None:
+        return resolved
+    if resolved in _allowed_models or (requested or "") in _allowed_models:
+        return resolved
+    raise EngineGuardError(
+        f"model {requested!r} is not served by this node "
+        f"(serves: {', '.join(allowed_models()) or 'nothing'})")
+
+
+# --------------------------------------------------------------------------
+# 3. Message / tool sanitisation
+# --------------------------------------------------------------------------
+# "function" is the deprecated OpenAI spelling of "tool"; accepted so an older
+# OpenAI-compatible client is not broken by the guard.
+_ROLES = ("system", "developer", "user", "assistant", "tool", "function")
+_TOOL_NAME_RE = re.compile(r"^[A-Za-z0-9_.\-]{1,64}$")
+_MAX_TOOL_DEPTH = 8
+# Ceiling on ONE recorded tool call's `arguments`. Real arguments are a small JSON
+# object; this only bites on abuse. Without it, `arguments` was the one field in a
+# message that was copied through at *any* length — see the accounting in
+# `sanitize_messages`.
+MAX_TOOL_ARG_BYTES = 8192
+
+
+def _content_to_text(content: Any) -> str:
+    """Text of a message. A list of parts is flattened to its text parts ONLY — the
+    non-text parts (image_url, input_audio, arbitrary dicts) are deliberately dropped
+    rather than forwarded, so a caller cannot smuggle bytes into the engine through a
+    content part."""
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for p in content:
+            if isinstance(p, str):
+                parts.append(p)
+            elif isinstance(p, dict) and isinstance(p.get("text"), str):
+                parts.append(p["text"])
+        return " ".join(x for x in parts if x)
+    raise EngineGuardError("message content must be text (or text parts)")
+
+
+def _sanitize_tool_calls(calls: Any) -> List[Dict]:
+    """Assistant tool-call history, reduced to id/type/function{name,arguments}."""
+    out: List[Dict] = []
+    if not isinstance(calls, list):
+        return out
+    for c in calls[:CONFIG.node_max_tools]:
+        if not isinstance(c, dict):
+            continue
+        fn = c.get("function")
+        if not isinstance(fn, dict):
+            continue
+        name = str(fn.get("name") or "")
+        if not _TOOL_NAME_RE.match(name):
+            raise EngineGuardError(f"illegal tool name in history: {name!r}")
+        args = fn.get("arguments")
+        if isinstance(args, dict):
+            encoded = json.dumps(args, default=str).encode("utf-8", "ignore")
+            if len(encoded) > MAX_TOOL_ARG_BYTES:
+                # Over-cap: degrade the object to truncated text rather than forward
+                # megabytes of it. Shape is preserved for the honest (small) case.
+                args = encoded[:MAX_TOOL_ARG_BYTES].decode("utf-8", "ignore")
+        elif isinstance(args, str):
+            raw = args.encode("utf-8", "ignore")
+            if len(raw) > MAX_TOOL_ARG_BYTES:
+                args = raw[:MAX_TOOL_ARG_BYTES].decode("utf-8", "ignore")
+        else:
+            args = ""
+        clean: Dict = {"type": "function", "function": {"name": name, "arguments": args}}
+        if isinstance(c.get("id"), str):
+            clean["id"] = c["id"][:128]
+        out.append(clean)
+    return out
+
+
+def sanitize_messages(messages: Any) -> List[Dict]:
+    """Strip every field the engine did not need to see, and bound the prompt.
+
+    This is the field-injection kill: whatever the API client (or a compromised
+    gateway) attached to a message, only the four chat fields survive.
+    """
+    if not isinstance(messages, list):
+        raise EngineGuardError("messages must be a list")
+    if len(messages) > CONFIG.node_max_messages:
+        raise EngineGuardError(
+            f"too many messages ({len(messages)} > {CONFIG.node_max_messages})")
+
+    out: List[Dict] = []
+    total = 0
+    for m in messages:
+        if not isinstance(m, dict):
+            raise EngineGuardError("each message must be an object")
+        role = str(m.get("role") or "user")
+        if role not in _ROLES:
+            raise EngineGuardError(f"unknown message role {role!r}")
+        clean: Dict = {"role": role, "content": _content_to_text(m.get("content"))}
+        name = m.get("name")
+        if isinstance(name, str) and name:
+            clean["name"] = name[:128]
+        tcid = m.get("tool_call_id")
+        if isinstance(tcid, str) and tcid:
+            clean["tool_call_id"] = tcid[:128]
+        if role == "assistant" and m.get("tool_calls"):
+            tcs = _sanitize_tool_calls(m.get("tool_calls"))
+            if tcs:
+                clean["tool_calls"] = tcs
+        # COUNT EVERY BYTE THAT ACTUALLY LEAVES FOR THE ENGINE, not just `content`.
+        # Counting content alone left `tool_calls[].function.arguments` (and `name` /
+        # `tool_call_id`) entirely outside the cap: one legal 8 MB WebSocket frame
+        # carried 7.5 MB of tool-call arguments past a 1 MB documented limit, and
+        # unconstrained by the frame the same shape reached gigabytes.
+        total += len(clean["content"].encode("utf-8", "ignore")) + 32
+        total += len(clean.get("name", "")) + len(clean.get("tool_call_id", ""))
+        if clean.get("tool_calls"):
+            total += len(json.dumps(clean["tool_calls"],
+                                    default=str).encode("utf-8", "ignore"))
+        if total > CONFIG.node_max_prompt_bytes:
+            raise EngineGuardError(
+                f"prompt exceeds this node's {CONFIG.node_max_prompt_bytes} byte limit")
+        out.append(clean)
+    return out
+
+
+def _depth_ok(obj: Any, depth: int = 0) -> bool:
+    if depth > _MAX_TOOL_DEPTH:
+        return False
+    if isinstance(obj, dict):
+        return all(_depth_ok(v, depth + 1) for v in obj.values())
+    if isinstance(obj, list):
+        return all(_depth_ok(v, depth + 1) for v in obj)
+    return True
+
+
+def sanitize_tools(tools: Any, *, tool_choice: Any = None) -> "Optional[List[Dict]]":
+    """Bound and scrub tool DEFINITIONS before they reach a chat template.
+
+    Returns None when there is nothing to send — including when the owner has turned
+    definition passthrough off (``STEVAI_NODE_ALLOW_TOOL_DEFS=0``) and when
+    ``tool_choice`` is "none", which is enforced here by withholding the tools
+    entirely rather than trusting the engine to honour a flag.
+
+    NOTE: forwarding a definition is not executing anything. Nothing on the node runs
+    a tool — see ``assert_tool_execution_allowed``.
+    """
+    if tool_choice == "none" or not tools:
+        return None
+    if not CONFIG.node_allow_tool_defs:
+        return None
+    if not isinstance(tools, list):
+        raise EngineGuardError("tools must be a list")
+    if len(tools) > CONFIG.node_max_tools:
+        raise EngineGuardError(f"too many tools ({len(tools)} > {CONFIG.node_max_tools})")
+
+    out: List[Dict] = []
+    for t in tools:
+        if not isinstance(t, dict):
+            raise EngineGuardError("each tool must be an object")
+        if str(t.get("type") or "function") != "function":
+            raise EngineGuardError(f"unsupported tool type {t.get('type')!r}")
+        fn = t.get("function")
+        if not isinstance(fn, dict):
+            raise EngineGuardError("tool.function must be an object")
+        name = str(fn.get("name") or "")
+        if not _TOOL_NAME_RE.match(name):
+            raise EngineGuardError(f"illegal tool name {name!r}")
+        clean_fn: Dict = {"name": name}
+        desc = fn.get("description")
+        if isinstance(desc, str) and desc:
+            clean_fn["description"] = desc[:1024]
+        params = fn.get("parameters")
+        if params is not None:
+            if not isinstance(params, dict):
+                raise EngineGuardError(f"tool {name!r}: parameters must be an object")
+            if not _depth_ok(params):
+                raise EngineGuardError(f"tool {name!r}: parameter schema nests too deeply")
+            clean_fn["parameters"] = params
+        out.append({"type": "function", "function": clean_fn})
+
+    size = len(json.dumps(out, default=str).encode("utf-8", "ignore"))
+    if size > CONFIG.node_max_tool_bytes:
+        raise EngineGuardError(
+            f"tool schemas exceed this node's {CONFIG.node_max_tool_bytes} byte limit")
+    return out or None
+
+
+def sanitize_tool_choice(tool_choice: Any) -> Any:
+    """Normalise tool_choice to the small set of shapes an engine may be told about."""
+    if tool_choice is None:
+        return None
+    if isinstance(tool_choice, str):
+        if tool_choice in ("none", "auto", "required"):
+            return tool_choice
+        raise EngineGuardError(f"unknown tool_choice {tool_choice!r}")
+    if isinstance(tool_choice, dict):
+        fn = tool_choice.get("function")
+        name = str((fn or {}).get("name") or "") if isinstance(fn, dict) else ""
+        if not _TOOL_NAME_RE.match(name):
+            raise EngineGuardError("tool_choice must name a valid function")
+        return {"type": "function", "function": {"name": name}}
+    raise EngineGuardError("tool_choice must be a string or a function selector")
+
+
+# --------------------------------------------------------------------------
+# 4. Node-side tool EXECUTION — trust-gated, off by default, absent today
+# --------------------------------------------------------------------------
+def tool_execution_allowed(trust: str) -> bool:
+    """May THIS node run a tool the model asked for, on the host?
+
+    Two independent conditions, both required:
+      * the operator labelled this node ``owned``/``trusted`` (never self-declared —
+        the label arrives from the gateway, which got it from directory policy), and
+      * the machine's owner opted in (``STEVAI_NODE_ALLOW_TOOL_EXEC=1``).
+
+    An untrusted consumer node can therefore never be talked into running anything,
+    whatever the env says. Today nothing on the node executes tools at all: the model's
+    ``tool_calls`` are returned to the API client, which owns the executor. This gate
+    exists so that seam cannot be crossed by accident later.
+    """
+    return bool(CONFIG.node_allow_tool_exec) and (trust or "untrusted") in _TRUSTED_LABELS
+
+
+def assert_tool_execution_allowed(trust: str, tool_name: str = "") -> None:
+    if not tool_execution_allowed(trust):
+        raise EngineGuardError(
+            f"this node will not execute host-side tools"
+            f"{f' (requested: {tool_name!r})' if tool_name else ''}: "
+            f"trust={trust or 'untrusted'}, "
+            f"owner opt-in={'on' if CONFIG.node_allow_tool_exec else 'off'}")
+
+
+# --------------------------------------------------------------------------
+# 5. Generation budget
+# --------------------------------------------------------------------------
+def ollama_options() -> Dict[str, int]:
+    """Explicit generation bounds for Ollama. Before this the payload carried NO
+    options at all, so a job generated until the context window filled."""
+    return {
+        "num_ctx": int(CONFIG.node_max_context_tokens),
+        "num_predict": int(CONFIG.node_max_output_tokens),
+    }
+
+
+def sanitize_think(value: object) -> "Optional[bool]":
+    """Normalise the job's thinking hint to a strict bool, or None to leave it to the model.
+
+    MEASURED, 2026-08-21: a reasoning model spent ~20 seconds of GPU time — real electricity,
+    which is what we bill on — producing hundreds of thinking tokens before answering "PONG".
+    On turns that need no reasoning that is pure waste, paid for by the user and the operator
+    and felt as a slow answer.
+
+    Ollama's `think` is silently ignored by models that do not reason, so sending it is safe
+    across a mixed fleet. It is normalised here rather than passed through because it arrives
+    in a JOB, and a job is caller-controlled input: anything but a real bool is discarded.
+    """
+    return value if isinstance(value, bool) else None
+
+
+def sanitize_think_effort(value: object) -> str:
+    """Normalise the job's effort tier to one of `thinkbudget.TIERS`, or "" for "not stated".
+
+    AN ALLOW-LIST, like every other field that arrives in a JOB. `sanitize_think` next door takes a
+    strict bool for the same reason: a job is caller-controlled input, and a node that accepted an
+    arbitrary string here would forward it to the engine as a reasoning level. "" means the node
+    applies no cap and asks for no level, which is exactly today's behaviour — so a gateway that has
+    not been redeployed is unaffected.
+    """
+    from . import thinkbudget
+    return value if isinstance(value, str) and value in thinkbudget.TIERS else ""
+
+
+#: Reasoning budgets are stated in TOKENS (that is what a model spends and what we bill), and the
+#: cap is enforced over CHARACTERS, because a delta is text and no tokeniser is available on the
+#: streaming path. Four is the usual English ratio and the conversion is deliberately generous: a
+#: cap that fired early would truncate reasoning a turn had legitimately earned.
+CHARS_PER_TOKEN = 4
+
+
+def reasoning_char_budget(effort: str) -> "Optional[int]":
+    """The character cap for this tier, or None for unbounded/not-stated."""
+    from . import thinkbudget
+    if not effort:
+        return None
+    toks = thinkbudget.max_reasoning_tokens(effort)
+    return None if toks is None else toks * CHARS_PER_TOKEN
+
+
+def llamacpp_max_tokens(requested: int = 0) -> int:
+    """Output budget for a llama.cpp turn, clamped to the node's ceiling. Reasoning
+    models legitimately need a large budget, which is why this ceiling is separate
+    from the Ollama one."""
+    ceiling = int(CONFIG.node_max_output_tokens_llamacpp)
+    want = int(requested or 0) or ceiling
+    return max(1, min(want, ceiling))
+
+
+class OutputMeter:
+    """Hard byte ceiling on what one job may produce, independent of the engine.
+
+    ``num_predict``/``max_tokens`` are hints an engine may ignore or mis-apply; this
+    is the backstop that actually stops a runaway generation from filling a
+    volunteer's RAM and the 8 MB result frame.
+    """
+
+    def __init__(self, max_bytes: "Optional[int]" = None) -> None:
+        self.max_bytes = int(max_bytes or CONFIG.node_max_output_bytes)
+        self.total = 0
+
+    def add(self, text: str) -> str:
+        self.total += len((text or "").encode("utf-8", "ignore"))
+        if self.total > self.max_bytes:
+            raise EngineGuardError(
+                f"engine output exceeded this node's {self.max_bytes} byte limit — job cancelled")
+        return text
+
+
+def check_voice_sample(sample: "Optional[bytes]") -> "Optional[bytes]":
+    """Bound attacker-supplied media before it is written anywhere or handed to a
+    C/C++/torch decoder. The gateway also scans it; this is the node's own check,
+    because a node must not depend on its gateway having done the right thing."""
+    if not sample:
+        return None
+    cap = int(CONFIG.node_max_voice_sample_bytes)
+    if len(sample) > cap:
+        raise EngineGuardError(f"voice sample exceeds this node's {cap} byte limit")
+    return sample
+
+
+# --------------------------------------------------------------------------
+# 6. Least-privilege process posture
+# --------------------------------------------------------------------------
+# Variables a child genuinely needs to run. EVERYTHING else — every cloud token,
+# every API key the owner exported into their shell — is dropped.
+_ENV_KEEP = (
+    "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+    "TMPDIR", "TEMP", "TMP", "PWD",
+    # Windows needs these to start a process at all.
+    "SystemRoot", "SystemDrive", "windir", "COMSPEC", "PATHEXT", "USERPROFILE",
+    "APPDATA", "LOCALAPPDATA", "NUMBER_OF_PROCESSORS", "PROCESSOR_ARCHITECTURE",
+    # TLS trust + native libs + GPU visibility.
+    "SSL_CERT_FILE", "SSL_CERT_DIR", "REQUESTS_CA_BUNDLE", "LD_LIBRARY_PATH",
+    "DYLD_LIBRARY_PATH", "CUDA_VISIBLE_DEVICES", "NVIDIA_VISIBLE_DEVICES",
+    # Python needs to find itself and the package.
+    "PYTHONPATH", "PYTHONHOME", "VIRTUAL_ENV", "PYTHONIOENCODING",
+)
+# Our own config travels; nothing else with a prefix does.
+_ENV_KEEP_PREFIXES = ("STEVAI_", "OLLAMA_")
+
+
+def minimal_env(extra: "Optional[Dict[str, str]]" = None,
+                *, keep: Iterable[str] = _ENV_KEEP,
+                keep_prefixes: Iterable[str] = _ENV_KEEP_PREFIXES) -> Dict[str, str]:
+    """A child's environment, built by allowlist instead of inherited wholesale.
+
+    ``{**os.environ}`` on a developer's or a company server's machine hands the child
+    every credential on the box. This does not.
+    """
+    env: Dict[str, str] = {}
+    prefixes = tuple(keep_prefixes)
+    for k, v in os.environ.items():
+        if k in keep or (prefixes and k.startswith(prefixes)):
+            env[k] = v
+    for k, v in (extra or {}).items():
+        if v is None:
+            env.pop(k, None)
+        else:
+            env[k] = str(v)
+    return env
+
+
+def node_home() -> Path:
+    """This node's private directory.
+
+    ``$STEVAI_WORKSPACE`` wins when the supervisor provided one — the supervisor has
+    been setting it and, until now, nothing read it, so its "wipe on stop" only ever
+    deleted a marker file. Anything we put here is genuinely wiped when sharing stops.
+    """
+    ws = (envvar("WORKSPACE") or "").strip()
+    root = Path(ws) if ws else config_dir() / "node"
+    return root
+
+
+def _private_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path, stat.S_IRWXU)          # 0700 — owner only (no-op on Windows)
+    except OSError:
+        pass
+    return path
+
+
+def models_dir() -> Path:
+    """Where the node keeps ITS models. Separate from ``~/.ollama`` on purpose: network
+    jobs must not read, evict or grow the owner's personal model store."""
+    override = (envvar("NODE_MODELS_DIR") or "").strip()
+    return _private_dir(Path(override) if override else node_home() / "models")
+
+
+def scratch_dir() -> Path:
+    """Node-private scratch for untrusted bytes (e.g. a voice sample), instead of the
+    world-readable global temp directory."""
+    return _private_dir(node_home() / "scratch")
+
+
+def engine_env(*, host: str = "127.0.0.1:11434",
+               models: "Optional[str]" = None,
+               extra: "Optional[Dict[str, str]]" = None) -> Dict[str, str]:
+    """Environment for an engine daemon WE start: loopback bind, private model store,
+    no inherited secrets. (Installs where a shell script or Electron starts the engine
+    do not go through here — see the module docstring.)"""
+    env = {
+        "OLLAMA_HOST": host,
+        "OLLAMA_MODELS": models or str(models_dir()),
+        "OLLAMA_ORIGINS": "http://127.0.0.1",   # no drive-by from a web page
+        "OLLAMA_NOHISTORY": "1",
+    }
+    env.update(extra or {})
+    return minimal_env(env)
+
+
+# --------------------------------------------------------------------------
+# 7. Transport — the only place job-handling code talks to an engine
+# --------------------------------------------------------------------------
+async def post_json(base: str, path: str, payload: Dict, timeout: float) -> Dict:
+    """One guarded, non-streaming request. Raises on any transport/engine failure so
+    the caller re-routes rather than inventing an answer."""
+    url = engine_url(base, path)
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        r = await client.post(url, json=payload)
+        r.raise_for_status()
+        return r.json()
+
+
+@asynccontextmanager
+async def stream(base: str, path: str, payload: Dict, timeout: float):
+    """One guarded streaming request. Yields the response object; leaving the block
+    closes the stream, which is what actually stops the engine generating."""
+    url = engine_url(base, path)
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        async with client.stream("POST", url, json=payload) as r:
+            r.raise_for_status()
+            yield r