pal-code 0.1.0__py3-none-any.whl

pal/orchestrator/pipeline.py

@@ -0,0 +1,228 @@
+from typing import TYPE_CHECKING, Optional
+
+from pal.access_manager.components.base import AccessDecision, OperationType
+from pal.access_manager.pipeline import AccessManagerPipeline
+from pal.llm_wrapper.components.base import LLMSyscall, LLMWrapper
+from pal.orchestrator.components.agent import AgentConfig
+from pal.orchestrator.components.cgroup_manager import CgroupManager, create_resource_manager
+from pal.orchestrator.components.scheduler import Scheduler
+from pal.orchestrator.components.syscall_scheduler import SchedulingStrategy, SyscallRequest, SyscallScheduler
+from pal.orchestrator.utils.device import ToolDevice
+from pal.storage_manager.components.base import StorageSyscall
+from pal.storage_manager.components.storage_queue import StorageRequest
+from pal.storage_manager.pipeline import StorageManagerPipeline
+from pal.storage_manager.utils.sdk import StorageSDK
+from pal.tool_manager.components.base import ToolCallResult, ToolParam
+from pal.tool_manager.components.tool_call_queue import QueuedToolCall
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+if TYPE_CHECKING:
+    from pal.memory.pipeline import MemoryPipeline
+
+
+class OrchestratorPipeline:
+    """
+    Top-level entry point for agent orchestration: submit agent configs,
+    admit them onto a bounded number of concurrent cgroup-isolated
+    processes, and optionally expose a tool device those agent
+    processes can call back into.
+
+    Also owns the centralized syscall queue (SyscallScheduler): every
+    LLM inference request in the system, from any module, is meant to
+    go through submit_syscall() here rather than each caller hitting an
+    LLMWrapper directly -- that's what "centralize all queues within the
+    scheduler module" means in practice (AIOS 3.3).
+
+    And owns the Storage Manager (AIOS 3.6): one StorageManagerPipeline
+    shared by every agent/pipeline in the system, for both the memory
+    manager's RAM-to-disk swaps (see pal/memory/pipeline.py's
+    storage_manager= parameter) and an agent's own direct storage SDK
+    calls (storage_sdk_for()).
+
+    And owns the Tool Manager (AIOS 3.7): one ToolManagerPipeline
+    (standardized loading, parameter validation, parallel-access
+    conflict resolution), wired into the ToolDevice transport so every
+    tool call an agent makes over the socket gets the same treatment
+    regardless of which agent or which tool.
+
+    And owns the Access Manager (AIOS 3.8): one AccessManagerPipeline,
+    wired into the StorageManagerPipeline so every cross-agent storage
+    request (StorageSDK.read_from()/write_to()/delete_from()) is
+    checked against a privilege-group hashmap, and every destructive
+    operation (delete, overwrite) goes through user intervention.
+    Agents are assigned a privilege group via assign_privilege_group()
+    or submit_agent(..., privilege_group=...).
+
+    And provides the AIOS SDK (AIOS 3.9) via sdk_for(agent_id,
+    core_config): one AgentSDK per agent, wired to every manager above,
+    which is the actual interface an agent developer builds against --
+    chat()/remember()/recall()/read()/write()/call_tool()/etc. -- rather
+    than any manager or syscall type directly.
+    """
+
+    def __init__(
+        self,
+        parent_slice: str = "pal.slice",
+        max_concurrent: int = 3,
+        tool_socket_path: str = None,  # a Unix socket path, or host:port (used on Windows)
+        syscall_strategy: SchedulingStrategy = SchedulingStrategy.FIFO,
+        rr_quantum: float = 2.0,
+        storage_root: str = None,
+        vector_persist_directory: str = None,
+        confirmation_handler=None,
+        resource_manager=None,
+    ):
+        self.cgroup_manager = resource_manager or create_resource_manager(parent_slice, manager_cls=CgroupManager)
+        self.scheduler = Scheduler(self.cgroup_manager, max_concurrent=max_concurrent)
+        self.syscall_scheduler = SyscallScheduler(strategy=syscall_strategy, rr_quantum=rr_quantum)
+        self.access_manager = AccessManagerPipeline(confirmation_handler=confirmation_handler)
+        self.storage_manager = StorageManagerPipeline(
+            root=storage_root, vector_persist_directory=vector_persist_directory, access_manager=self.access_manager
+        )
+        self.tool_manager = ToolManagerPipeline()
+        self.tool_device = ToolDevice(tool_socket_path, tool_manager=self.tool_manager) if tool_socket_path \
+            else ToolDevice(tool_manager=self.tool_manager)
+
+    def submit_agent(self, config: AgentConfig, priority: int = 0, weight: int = 100, privilege_group: str = None) -> None:
+        self.scheduler.submit(config, priority=priority, weight=weight)
+        if privilege_group is not None:
+            self.access_manager.assign_privilege_group(config.name, privilege_group)
+
+    def tick(self) -> list[str]:
+        return self.scheduler.tick()
+
+    def run_turn(self, agent_name: str, system_prompt: str, user_message: str, timeout: float = 60) -> dict:
+        agent = self.scheduler.running.get(agent_name)
+        if agent is None:
+            raise ValueError(f"agent {agent_name} is not running -- submit + tick first")
+        return agent.run_turn(system_prompt, user_message, timeout=timeout)
+
+    # -- centralized syscall scheduling (AIOS 3.3) -----------------------------
+
+    def submit_syscall(self, agent_name: str, core: LLMWrapper, syscall: LLMSyscall, priority: int = 0) -> str:
+        """Every LLM inference request funnels through here rather than
+        callers hitting core.chat()/core.stream_chat() directly, so
+        request ordering and time-slicing are handled in exactly one
+        place regardless of which module -- an Agent, the top-level
+        Pipeline, anything else -- issued the request."""
+        return self.syscall_scheduler.submit(agent_name, core, syscall, priority=priority)
+
+    def syscall_tick(self) -> SyscallRequest | None:
+        """Advances the syscall queue by one step, using whichever
+        strategy this orchestrator was configured with (FIFO or Round
+        Robin)."""
+        return self.syscall_scheduler.tick()
+
+    def drain_syscalls(self, max_ticks: int = 10_000) -> list[SyscallRequest]:
+        return self.syscall_scheduler.drain(max_ticks=max_ticks)
+
+    def syscall_result(self, request_id: str) -> SyscallRequest:
+        return self.syscall_scheduler.get_result(request_id)
+
+    # -- Storage Manager (AIOS 3.6) --------------------------------------------
+
+    def storage_sdk_for(self, agent_id: str) -> StorageSDK:
+        """What an agent calls to read/write its own persistent data --
+        "the agent calls the storage API in the SDK, which is further
+        converted into storage-related system calls and put into the
+        storage queue." Every StorageSDK instance shares this
+        orchestrator's one StorageManagerPipeline/queue, scoped by
+        agent_id."""
+        return StorageSDK(agent_id, self.storage_manager)
+
+    def submit_storage_syscall(self, syscall: StorageSyscall) -> str:
+        return self.storage_manager.submit(syscall)
+
+    def storage_tick(self) -> StorageRequest | None:
+        return self.storage_manager.tick()
+
+    def drain_storage_syscalls(self, max_iterations: int = 10_000) -> list[StorageRequest]:
+        return self.storage_manager.drain(max_iterations=max_iterations)
+
+    def storage_result(self, request_id: str) -> StorageRequest:
+        return self.storage_manager.get_result(request_id)
+
+    # -- Access Manager (AIOS 3.8) ----------------------------------------------
+
+    def assign_privilege_group(self, agent_id: str, group: str) -> None:
+        self.access_manager.assign_privilege_group(agent_id, group)
+
+    def set_confirmation_handler(self, handler) -> None:
+        """Registers the callback that answers user-intervention
+        prompts for irreversible operations (delete, overwrite,
+        privilege modification). The default handler denies everything,
+        so a real application needs to set one -- e.g. a CLI y/n prompt
+        or a UI confirmation dialog."""
+        self.access_manager.set_confirmation_handler(handler)
+
+    def check_access(self, requesting_agent_id: str, target_agent_id: str, operation: OperationType, resource: str = "") -> AccessDecision:
+        return self.access_manager.check_access(requesting_agent_id, target_agent_id, operation, resource=resource)
+
+    def register_tool(self, name: str, loader, params: list[ToolParam] = None,
+                       parallel_limit: int = None, dependencies: list[str] = None) -> None:
+        """Registers a tool with the Tool Manager (AIOS 3.7): `loader`
+        is called at most once, the first time this tool is actually
+        invoked (dynamic loading -- see ToolRegistry.get_callable).
+        Reachable both via the ToolDevice socket transport and directly
+        through invoke_tool() below."""
+        self.tool_device.register_tool(
+            name, loader, params=params, parallel_limit=parallel_limit, dependencies=dependencies
+        )
+
+    def invoke_tool(self, agent_id: str, tool_name: str, args: dict) -> ToolCallResult:
+        return self.tool_manager.invoke(agent_id, tool_name, args)
+
+    def submit_tool_call(self, agent_id: str, tool_name: str, args: dict) -> str:
+        return self.tool_manager.submit(agent_id, tool_name, args)
+
+    def dispatch_tool_call(self) -> QueuedToolCall | None:
+        return self.tool_manager.dispatch_next()
+
+    def drain_tool_calls(self, max_iterations: int = 10_000) -> list[QueuedToolCall]:
+        return self.tool_manager.drain(max_iterations=max_iterations)
+
+    # -- AIOS SDK (AIOS 3.9) -----------------------------------------------------
+
+    def sdk_for(self, agent_id: str, core_config, memory: Optional["MemoryPipeline"] = None):
+        """Builds an AgentSDK for one agent, wired to this
+        orchestrator's shared managers (storage, tools, access control)
+        and centralized LLM syscall scheduler -- the single object an
+        agent developer actually interacts with, abstracting away every
+        manager and syscall type above it. `core_config` is
+        agent-specific (different agents may run against different
+        backends/models), everything else is shared."""
+        from pal.llm_wrapper.pipeline import LLMWrapperPipeline
+        from pal.sdk.pipeline import AgentSDK
+
+        llm_wrapper = LLMWrapperPipeline(core_config)
+        return AgentSDK(
+            agent_id=agent_id,
+            llm_wrapper=llm_wrapper,
+            storage_manager=self.storage_manager,
+            tool_manager=self.tool_manager,
+            access_manager=self.access_manager,
+            memory=memory,
+            syscall_scheduler=self.syscall_scheduler,
+        )
+
+    def register_builtin_tools(self) -> None:
+        """Opt-in: registers the SDK's small built-in tool catalog
+        (pal/sdk/components/tool_catalog.py) with this
+        orchestrator's ToolManagerPipeline. Not called automatically --
+        a fresh OrchestratorPipeline starts with no tools registered,
+        exactly as before this existed; call this explicitly to make
+        the built-in catalog available."""
+        from pal.sdk.components.tool_catalog import register_builtin_tools
+        register_builtin_tools(self.tool_manager)
+
+    def start_tool_device(self) -> None:
+        self.tool_device.start()
+
+    def stop_tool_device(self) -> None:
+        self.tool_device.stop()
+
+    def status(self) -> dict:
+        return self.scheduler.status()
+
+    def stop_all(self) -> None:
+        self.scheduler.stop_all()

pal/orchestrator/utils/__init__.py

@@ -0,0 +1,4 @@
+from pal.orchestrator.utils.device import DEFAULT_SOCKET_PATH, ToolDevice, call_tool
+from pal.orchestrator.utils.protocol import ToolRequest, ToolResponse
+
+__all__ = ["ToolDevice", "call_tool", "DEFAULT_SOCKET_PATH", "ToolRequest", "ToolResponse"]

pal/orchestrator/utils/device.py

@@ -0,0 +1,164 @@
+"""Tool transport between agent processes and the orchestrator.
+
+Portable: a Unix domain socket where the OS has one (Linux, macOS), a loopback TCP socket where it
+does not (Windows). Requests and responses are one JSON object per line, so a message of any size
+is read completely (the old single recv() truncated anything over 64 KB). The Unix socket file is
+created owner-only (0600); the TCP fallback binds 127.0.0.1 only.
+
+Stands in for a future /dev/pal-tools character device: porting later means swapping this
+transport, not the protocol or how tool calls are handled.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import socket
+import tempfile
+import threading
+from collections.abc import Callable
+from typing import Optional
+
+from pal.orchestrator.utils.protocol import ToolRequest, ToolResponse
+from pal.tool_manager.pipeline import ToolManagerPipeline
+
+log = logging.getLogger(__name__)
+
+HAS_UNIX_SOCKETS = hasattr(socket, "AF_UNIX")
+DEFAULT_SOCKET_PATH = (
+    os.path.join(tempfile.gettempdir(), "pal-tools.sock") if HAS_UNIX_SOCKETS else "127.0.0.1:47613")
+MAX_MESSAGE_BYTES = 1_000_000
+_TCP = re.compile(r"^[A-Za-z0-9.\-]+:\d+$")
+
+
+def _is_tcp(address: str) -> bool:
+    return bool(_TCP.match(address))
+
+
+def _recv_line(conn: socket.socket) -> bytes:
+    buf = bytearray()
+    while b"\n" not in buf:
+        chunk = conn.recv(65536)
+        if not chunk:
+            break
+        buf += chunk
+        if len(buf) > MAX_MESSAGE_BYTES:
+            raise ValueError("message too large")
+    return bytes(buf)
+
+
+def _connect(address: str, timeout: float) -> socket.socket:
+    if _is_tcp(address) or not HAS_UNIX_SOCKETS:
+        host, _, port = address.rpartition(":")
+        return socket.create_connection((host or "127.0.0.1", int(port)), timeout=timeout)
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    sock.connect(address)
+    return sock
+
+
+class ToolDevice:
+    """Agents (in their own OS process) connect here to invoke tools; the orchestrator's process
+    executes them, giving one place to apply permissions and auditing per tool call.
+
+    With a ToolManagerPipeline, register_tool() registers a full ToolSpec (loader, params,
+    parallel_limit, dependencies). Without one it falls back to a plain name -> callable dict.
+    `address` is a Unix socket path or "host:port"; after start(), `.address` is the real one
+    (port 0 picks a free port)."""
+
+    def __init__(self, address: Optional[str] = None, tool_manager: Optional[ToolManagerPipeline] = None,
+                 socket_path: Optional[str] = None):
+        self.address = address or socket_path or DEFAULT_SOCKET_PATH
+        self.tool_manager = tool_manager
+        self._handlers: dict[str, Callable[[dict], dict]] = {}
+        self._server: Optional[socket.socket] = None
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+
+    @property
+    def socket_path(self) -> str:  # backwards-compatible name
+        return self.address
+
+    def register_tool(self, name: str, handler: Callable[[dict], dict], **tool_spec_kwargs) -> None:
+        if self.tool_manager is not None:
+            self.tool_manager.register_tool(name, handler, **tool_spec_kwargs)
+        else:
+            self._handlers[name] = handler
+
+    def start(self) -> None:
+        if self._running:
+            return
+        if _is_tcp(self.address) or not HAS_UNIX_SOCKETS:
+            host, _, port = self.address.rpartition(":")
+            self._server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self._server.bind((host or "127.0.0.1", int(port or 0)))
+            self.address = f"{self._server.getsockname()[0]}:{self._server.getsockname()[1]}"
+        else:
+            if os.path.exists(self.address):
+                os.remove(self.address)
+            self._server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self._server.bind(self.address)
+            os.chmod(self.address, 0o600)  # owner only
+        self._server.listen(5)
+        self._running = True
+        self._thread = threading.Thread(target=self._serve_loop, daemon=True)
+        self._thread.start()
+
+    def _serve_loop(self) -> None:
+        while self._running:
+            try:
+                self._server.settimeout(0.5)
+                conn, _ = self._server.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                break
+            threading.Thread(target=self._handle_conn, args=(conn,), daemon=True).start()
+
+    def _handle_conn(self, conn: socket.socket) -> None:
+        with conn:
+            conn.settimeout(30)
+            try:
+                raw = _recv_line(conn)
+                if not raw:
+                    return
+                req = ToolRequest.decode(raw)
+                if self.tool_manager is not None:
+                    result = self.tool_manager.invoke(req.agent_name, req.tool_name, req.args)
+                    resp = ToolResponse(ok=result.ok, result=result.result, error=result.error)
+                else:
+                    handler = self._handlers.get(req.tool_name)
+                    if handler is None:
+                        resp = ToolResponse(ok=False, error=f"unknown tool: {req.tool_name}")
+                    else:
+                        resp = ToolResponse(ok=True, result=handler(req.args))
+            except Exception as e:  # noqa: BLE001  (any failure becomes an error response)
+                log.warning("tool request failed: %s", e)
+                resp = ToolResponse(ok=False, error=str(e))
+            try:
+                conn.sendall(resp.encode())
+            except OSError:
+                pass
+
+    def stop(self) -> None:
+        self._running = False
+        if self._server:
+            self._server.close()
+        if HAS_UNIX_SOCKETS and not _is_tcp(self.address) and os.path.exists(self.address):
+            os.remove(self.address)
+
+
+def call_tool(agent_name: str, tool_name: str, args: dict, socket_path: Optional[str] = None,
+              timeout: float = 30, address: Optional[str] = None) -> dict:
+    """Client-side helper: what an agent process calls to invoke a tool."""
+    req = ToolRequest(agent_name=agent_name, tool_name=tool_name, args=args)
+    sock = _connect(address or socket_path or DEFAULT_SOCKET_PATH, timeout)
+    try:
+        sock.sendall(req.encode())
+        raw = _recv_line(sock)
+    finally:
+        sock.close()
+    resp = ToolResponse.decode(raw)
+    if not resp.ok:
+        raise RuntimeError(f"tool call failed: {resp.error}")
+    return resp.result

pal/orchestrator/utils/protocol.py

@@ -0,0 +1,32 @@
+import json
+from dataclasses import asdict, dataclass
+
+
+@dataclass
+class ToolRequest:
+    agent_name: str
+    tool_name: str
+    args: dict
+
+    def encode(self) -> bytes:
+        return (json.dumps(asdict(self)) + "\n").encode("utf-8")
+
+    @staticmethod
+    def decode(raw: bytes) -> "ToolRequest":
+        data = json.loads(raw.decode("utf-8"))
+        return ToolRequest(**data)
+
+
+@dataclass
+class ToolResponse:
+    ok: bool
+    result: object = None
+    error: str | None = None
+
+    def encode(self) -> bytes:
+        return (json.dumps(asdict(self)) + "\n").encode("utf-8")
+
+    @staticmethod
+    def decode(raw: bytes) -> "ToolResponse":
+        data = json.loads(raw.decode("utf-8"))
+        return ToolResponse(**data)

pal/os_kernel/__init__.py

@@ -0,0 +1,5 @@
+from pal.os_kernel.filesystem import OSKernelError, Workspace
+from pal.os_kernel.pipeline import OS_OPS, OSKernel
+from pal.os_kernel.sysinfo import system_info
+
+__all__ = ["OS_OPS", "OSKernel", "OSKernelError", "Workspace", "system_info"]

pal/os_kernel/filesystem.py

@@ -0,0 +1,80 @@
+"""File operations: the part of the OS kernel's filesystem an agent may touch.
+
+Every agent gets its own workspace folder. A path must be relative and stay inside it: no `..`, absolute paths,
+drive letters, backslashes or names Windows forbids, and a symlink that points outside is refused. Writes are atomic.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from pal.errors import UserInputError
+from pal.paths import atomic_write_bytes, is_safe_relative_key
+
+
+class OSKernelError(UserInputError):
+    """A request to the OS kernel was refused or failed. The message is safe to show."""
+
+
+class Workspace:
+    def __init__(self, root: Path, max_read: int, max_write: int, max_binary: int = 20_000_000):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.max_read = max_read
+        self.max_write = max_write
+        self.max_binary = max_binary
+
+    def resolve(self, rel: str) -> Path:
+        if not isinstance(rel, str) or not is_safe_relative_key(rel):
+            raise OSKernelError(f"invalid path: {rel!r} (use a relative path inside your workspace)")
+        target = (self.root / rel).resolve()
+        if self.root.resolve() not in target.parents:
+            raise OSKernelError(f"path escapes the workspace: {rel!r}")
+        return target
+
+    def exists(self, rel: str) -> bool:
+        return self.resolve(rel).is_file()
+
+    def read(self, rel: str) -> str:
+        p = self.resolve(rel)
+        if not p.is_file():
+            raise OSKernelError(f"no such file: {rel}")
+        if p.stat().st_size > self.max_read:
+            raise OSKernelError(f"{rel} is larger than the {self.max_read:,}-byte read limit")
+        return p.read_text(encoding="utf-8", errors="replace")
+
+    def read_bytes(self, rel: str) -> bytes:
+        p = self.resolve(rel)
+        if not p.is_file():
+            raise OSKernelError(f"no such file: {rel}")
+        if p.stat().st_size > self.max_binary:
+            raise OSKernelError(f"{rel} is larger than the {self.max_binary:,}-byte limit for binary files")
+        return p.read_bytes()
+
+    def write_bytes(self, rel: str, data: bytes) -> int:
+        if len(data) > self.max_binary:
+            raise OSKernelError(f"the data is larger than the {self.max_binary:,}-byte limit for binary files")
+        atomic_write_bytes(self.resolve(rel), bytes(data))
+        return len(data)
+
+    def write(self, rel: str, content: str) -> int:
+        data = str(content).encode("utf-8")
+        if len(data) > self.max_write:
+            raise OSKernelError(f"content is larger than the {self.max_write:,}-byte write limit")
+        atomic_write_bytes(self.resolve(rel), data)
+        return len(data)
+
+    def delete(self, rel: str) -> None:
+        p = self.resolve(rel)
+        if not p.is_file():
+            raise OSKernelError(f"no such file: {rel}")
+        p.unlink()
+
+    def list(self, prefix: str = "") -> list[str]:
+        base = self.root.resolve()
+        out = []
+        for p in sorted(base.rglob("*")):
+            if p.is_file() and not p.name.endswith(".tmp"):
+                rel = p.relative_to(base).as_posix()
+                if rel.startswith(prefix):
+                    out.append(rel)
+        return out

pal/os_kernel/network.py

@@ -0,0 +1,146 @@
+"""Network requests through the OS network stack, with the checks an agent-facing call needs.
+
+http and https only; no credentials in the URL; the host must resolve to a public address unless the settings allow
+private ones (blocks requests to localhost, the home network and cloud metadata endpoints); an optional host
+allow-list; a timeout; a response size cap; redirects are followed by hand so every hop is checked again.
+Residual risk, stated plainly: the address is checked before connecting, so a hostile DNS server that answers
+differently the second time (DNS rebinding) is not fully covered.
+"""
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import logging
+import socket
+import threading
+from collections.abc import Iterator
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from pal.os_kernel.filesystem import OSKernelError
+
+_MAX_REDIRECTS = 3
+
+
+def check_url(url: str, allow_private: bool, allowed_hosts: list[str]) -> None:
+    p = urlsplit(url)
+    if p.scheme not in ("http", "https") or not p.hostname:
+        raise OSKernelError("only http and https URLs are allowed")
+    if p.username or p.password:
+        raise OSKernelError("credentials inside a URL are not allowed")
+    host = p.hostname.lower()
+    if allowed_hosts and host not in {h.lower() for h in allowed_hosts}:
+        raise OSKernelError(f"host {host!r} is not on the allowed list")
+    try:
+        infos = socket.getaddrinfo(host, p.port or (443 if p.scheme == "https" else 80), type=socket.SOCK_STREAM)
+    except OSError as e:
+        raise OSKernelError(f"could not resolve {host!r}") from e
+    if allow_private:
+        return
+    for info in infos:
+        ip = ipaddress.ip_address(info[4][0])
+        if ip.is_private or ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_reserved or ip.is_unspecified:
+            raise OSKernelError(f"{host!r} resolves to a private or reserved address, which is blocked")
+
+
+# Headers a caller may set. Everything else (Host, Cookie, Proxy-*, X-Forwarded-*, ...) is refused, so a request cannot be made
+# to look like it came from somewhere else. These are the ones service APIs use for their keys.
+SAFE_HEADERS = frozenset({"authorization", "x-api-key", "x-rapidapi-key", "x-rapidapi-host", "ocp-apim-subscription-key",
+                          "x-goog-api-key", "x-goog-fieldmask", "content-type", "accept"})
+_TEXT_TYPES = ("application/json", "application/xml", "application/atom+xml", "application/xhtml+xml", "application/javascript")
+
+
+def clean_headers(headers: Any) -> dict:
+    out: dict = {}
+    for k, v in (headers or {}).items():
+        if not isinstance(k, str) or not isinstance(v, str):
+            raise OSKernelError("header names and values must be text")
+        if k.lower() not in SAFE_HEADERS:
+            raise OSKernelError(f"header {k!r} is not allowed")
+        if len(v) > 2000 or any(c in v for c in "\r\n\x00"):
+            raise OSKernelError(f"header {k!r} has an invalid value")
+        out[k] = v
+    return out
+
+
+def is_text(content_type: str) -> bool:
+    ct = content_type.split(";")[0].strip().lower()
+    return not ct or ct.startswith("text/") or ct in _TEXT_TYPES or ct.endswith(("+json", "+xml"))
+
+
+def safe_target(url: str) -> str:
+    """The URL without its query string, fragment or credentials: what is written to logs, because the query may hold an API key."""
+    p = urlsplit(url)
+    if not (p.scheme and p.hostname):
+        return ""
+    return f"{p.scheme}://{p.hostname}{f':{p.port}' if p.port else ''}{p.path}"
+
+
+_quiet_lock = threading.Lock()
+_quiet_depth = 0
+_quiet_saved = logging.NOTSET
+
+
+@contextlib.contextmanager
+def _quiet_http_logs() -> Iterator[None]:
+    """urllib3's DEBUG log line holds the full request URL, query string included, and so would put an API key in a log file for
+    anyone running with debug logging. Silence it for the length of a request (counted, so overlapping requests are safe)."""
+    global _quiet_depth, _quiet_saved
+    lg = logging.getLogger("urllib3")
+    with _quiet_lock:
+        if _quiet_depth == 0:
+            _quiet_saved = lg.level
+            lg.setLevel(logging.WARNING)
+        _quiet_depth += 1
+    try:
+        yield
+    finally:
+        with _quiet_lock:
+            _quiet_depth -= 1
+            if _quiet_depth == 0:
+                lg.setLevel(_quiet_saved)
+
+
+def request(method: str, url: str, *, allow_private: bool, allowed_hosts: list[str], timeout: float, max_bytes: int,
+            json: Any = None, headers: dict | None = None, data: bytes | None = None, max_binary_bytes: int | None = None,
+            keep_binary: bool = False) -> dict:
+    """One HTTP request with the checks above. `headers` must already be cleaned. A text answer comes back as `text` (at most
+    `max_bytes`); with `keep_binary` any other answer comes back as `body` bytes (at most `max_binary_bytes`) and `text` is empty.
+    Redirects are followed by hand and the caller's headers are NOT sent to the new address (they hold keys)."""
+    with _quiet_http_logs():
+        return _request(method, url, allow_private, allowed_hosts, timeout, max_bytes, json, headers, data, max_binary_bytes, keep_binary)
+
+
+def _request(method: str, url: str, allow_private: bool, allowed_hosts: list[str], timeout: float, max_bytes: int, json: Any,
+             headers: dict | None, data: bytes | None, max_binary_bytes: int | None, keep_binary: bool) -> dict:
+    import requests
+
+    sent = dict(headers or {})
+    for _ in range(_MAX_REDIRECTS + 1):
+        check_url(url, allow_private, allowed_hosts)
+        try:
+            resp = requests.request(method, url, json=json, data=data, timeout=timeout, allow_redirects=False, stream=True,
+                                    headers={"User-Agent": "pal-code", **sent})
+        except requests.RequestException as e:
+            raise OSKernelError(f"request failed: {type(e).__name__}") from e
+        if resp.is_redirect and resp.headers.get("Location"):
+            url, json, data, method, sent = urljoin(url, resp.headers["Location"]), None, None, "GET", {}
+            resp.close()
+            continue
+        ctype = resp.headers.get("Content-Type", "")
+        textual = is_text(ctype) or not keep_binary
+        cap = max_bytes if textual else (max_binary_bytes or max_bytes)
+        body = b""
+        for chunk in resp.iter_content(8192):
+            body += chunk
+            if len(body) > cap:
+                body = body[:cap]
+                break
+        resp.close()
+        out = {"status": resp.status_code, "content_type": ctype, "truncated": len(body) >= cap, "bytes": len(body)}
+        if textual:
+            out["text"] = body.decode(resp.encoding or "utf-8", errors="replace")
+        else:
+            out["text"], out["body"] = "", body
+        return out
+    raise OSKernelError("too many redirects")