ph-runtime-guest 0.1.0__py3-none-any.whl

ph_runtime/__init__.py

@@ -0,0 +1,23 @@
+"""The guest half of pH's Python code runtime.
+
+Runs inside `$PH_CACHE/runtime-venv`, in a subprocess the host spawns per agent,
+and reaches the host over one framed channel on fd 3. It imports neither
+`ph-core` nor `ph-rlm`: the process boundary exists so that model code cannot
+reach the harness, and importing the harness would put it back inside.
+
+@module ph_runtime
+"""
+
+from __future__ import annotations
+
+from .errors import RunStopped, ToolFailed
+from .protocol import PROTOCOL_FD, PROTOCOL_VERSION
+from .skill import wrap_skill_module
+
+__all__ = [
+    "PROTOCOL_FD",
+    "PROTOCOL_VERSION",
+    "RunStopped",
+    "ToolFailed",
+    "wrap_skill_module",
+]

ph_runtime/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m ph_runtime` — how the host spawns the guest."""
+
+from __future__ import annotations
+
+import sys
+
+from .runner import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ph_runtime/_json.py

@@ -0,0 +1,41 @@
+"""The narrowings `ph_runtime` needs from `ph.json` — a copy, pinned by a test.
+
+This package ships into the guest venv with `dill` as its only dependency, so it
+cannot import `ph.json`: that module lives in the ph-core wheel, and depending on
+the wheel is the thing this package exists not to do.
+
+**Copied by hand, compared character for character by
+`test_protocol_mirror.py`.** What keeps the two in step is the test rather than
+anyone's memory — that file opens by recording that *"a third copy that no test
+compared had already drifted"*. When it fails, copy the definition across again;
+when the guest comes to need a second narrowing, paste that one in and the test
+picks it up by name.
+
+The arrangement `truncation_marker` already has in `ph_runtime.protocol` — the
+other thing this package copies rather than imports — though that one is held to
+ph-core's by its output and this by its source, because a marker is a sentence
+built from two numbers and a narrowing is its text.
+
+Private, and re-exported by `ph_runtime.protocol` for the names the guest uses:
+this is ph-core's code, not the guest's API.
+
+@module ph_runtime._json
+"""
+
+from __future__ import annotations
+
+
+def as_str(value: object, default: str = "") -> str:
+    """A JSON string, or `default` — the fourth of the family, and the copied one.
+
+    One policy, the one `as_int`'s docstring argues for: a mis-shaped field
+    answers with the empty value rather than raising, because a reader of a log
+    some other build wrote must lose a row and not a session.
+
+    **Not `str(value)`**, which is what a reader writes without this and is worse
+    than useless: `str(None)` is `"None"` and `str(3)` is `"3"`, so a field that
+    is absent or of the wrong type comes back as a plausible-looking answer that
+    no assertion catches. Narrowing says "this was not a string" by giving back
+    nothing, which is the same thing `as_obj` and `as_seq` say.
+    """
+    return value if isinstance(value, str) else default

ph_runtime/cell.py

@@ -0,0 +1,193 @@
+"""Compiling one cell so that `await`, `return` and persistence all hold.
+
+Three requirements pull against each other, and the way they are reconciled is
+the only interesting thing in this module.
+
+1. **`await` at the top level.** The program is a coroutine on the child's one
+   loop, so there is no `nest_asyncio` question and no second loop to re-enter.
+2. **`return` at the top level.** A bare `return` is a syntax error in module
+   code even with `PyCF_ALLOW_TOP_LEVEL_AWAIT`, so the body is wrapped in an
+   `async def` — which is also what makes (1) fall out for free.
+3. **Names persist across cells.** But a name assigned inside a function is
+   *local* to it, so the naive wrapping loses every variable the cell defined —
+   which would quietly undo the whole point of a persistent namespace.
+
+So the wrapper declares every name the cell binds at its top level as `global`.
+That is what this module computes: the bound-name set, from the AST, including
+the cases that are easy to forget — `import`, `with ... as`, `for`, `except ...
+as`, walrus, `del`, and function and class definitions.
+
+A trailing expression becomes the cell's value, as it would in a REPL, so
+`stdout / stderr / result / traceback` reads the way prime-agent's did.
+
+@module ph_runtime.cell
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+__all__ = [
+    "CELL_FILENAME",
+    "CELL_FUNCTION",
+    "MAGIC_HINT",
+    "MAGIC_PREFIXES",
+    "bound_names",
+    "compile_cell",
+]
+
+CELL_FUNCTION = "__ph_cell__"
+
+CELL_FILENAME = "<cell>"
+"""The compiled name. Also the marker a traceback is trimmed to, so the model
+sees its own frames and not the runner's."""
+
+MAGIC_PREFIXES = ("%%", "%", "!")
+"""Every IPython escape, exported because three layers describe this rule.
+
+The guest refuses them, the RLM doctrine tells the model so, and the conformance
+suite checks the two agree. A hole left in one prefix is the hole, so the list
+has one home rather than three that drift."""
+
+MAGIC_HINT = (
+    "IPython magics are not available: pH runs plain Python, so there is no "
+    "`%%bash` to bypass the tool pipeline. Use `await tools.bash(command=...)` "
+    "for a shell, and ordinary Python for the rest."
+)
+"""Attached to the `SyntaxError` a magic produces (D2).
+
+The magic was the bypass — one shell command per cell that no `tools/pre-execute`
+listener, no approval and no sandbox `confine()` ever saw. Removing the
+mechanism closes the hole, so the error explains the governed route rather than
+apologising for a missing feature.
+"""
+
+
+def bound_names(body: list[ast.stmt]) -> set[str]:
+    """Every name the cell's *top level* binds, so the wrapper can globalize it.
+
+    Only the top level: a name bound inside a nested function or comprehension
+    is local to it in module code too, so declaring it global would change the
+    program's meaning rather than preserve it.
+    """
+    found: set[str] = set()
+
+    def add_target(node: ast.expr) -> None:
+        if isinstance(node, ast.Name):
+            found.add(node.id)
+        elif isinstance(node, ast.Starred):
+            add_target(node.value)
+        elif isinstance(node, (ast.Tuple, ast.List)):
+            for element in node.elts:
+                add_target(element)
+
+    def walk_expression(node: ast.expr) -> None:
+        # A walrus binds in the enclosing scope, so `if (n := len(x)) > 3:` at
+        # the top level defines `n` for later cells.
+        for child in ast.walk(node):
+            if isinstance(child, ast.NamedExpr):
+                add_target(child.target)
+
+    for statement in body:
+        if isinstance(statement, (ast.Assign,)):
+            for target in statement.targets:
+                add_target(target)
+            walk_expression(statement.value)
+        elif isinstance(statement, (ast.AugAssign, ast.AnnAssign)):
+            add_target(statement.target)
+            if statement.value is not None:
+                walk_expression(statement.value)
+        elif isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            found.add(statement.name)
+        elif isinstance(statement, (ast.Import, ast.ImportFrom)):
+            for alias in statement.names:
+                if alias.name == "*":
+                    continue
+                found.add(alias.asname or alias.name.split(".")[0])
+        elif isinstance(statement, (ast.For, ast.AsyncFor)):
+            add_target(statement.target)
+            found |= bound_names(statement.body) | bound_names(statement.orelse)
+        elif isinstance(statement, (ast.While, ast.If)):
+            walk_expression(statement.test)
+            found |= bound_names(statement.body) | bound_names(statement.orelse)
+        elif isinstance(statement, (ast.With, ast.AsyncWith)):
+            for item in statement.items:
+                if item.optional_vars is not None:
+                    add_target(item.optional_vars)
+            found |= bound_names(statement.body)
+        elif isinstance(statement, ast.Try):
+            found |= bound_names(statement.body) | bound_names(statement.orelse)
+            found |= bound_names(statement.finalbody)
+            for handler in statement.handlers:
+                if handler.name:
+                    found.add(handler.name)
+                found |= bound_names(handler.body)
+        elif isinstance(statement, ast.Match):
+            for case in statement.cases:
+                found |= bound_names(case.body)
+                for child in ast.walk(case.pattern):
+                    if isinstance(child, ast.MatchAs | ast.MatchStar) and child.name:
+                        found.add(child.name)
+                    elif isinstance(child, ast.MatchMapping) and child.rest:
+                        found.add(child.rest)
+        elif isinstance(statement, ast.Delete):
+            # `del x` needs `global x` too, or it raises for a name that is in
+            # globals but not local.
+            for target in statement.targets:
+                add_target(target)
+        elif isinstance(statement, (ast.Expr, ast.Return)) and statement.value is not None:
+            walk_expression(statement.value)
+
+    return found
+
+
+def compile_cell(program: str, filename: str = CELL_FILENAME) -> Any:  # noqa: ANN401
+    """Compile `program` into a module that defines `CELL_FUNCTION`.
+
+    :raises SyntaxError: the program does not parse. A magic gets `MAGIC_HINT`
+        appended, because that is the one syntax error with a governed answer.
+    """
+    try:
+        tree = ast.parse(program)
+    except SyntaxError as error:
+        if _looks_like_magic(program):
+            raise SyntaxError(f"{error.msg}. {MAGIC_HINT}") from error
+        raise
+
+    body = list(tree.body)
+    if body and isinstance(body[-1], ast.Expr):
+        last = body[-1]
+        body[-1] = ast.copy_location(ast.Return(value=last.value), last)
+
+    declarations: list[ast.stmt] = []
+    names = sorted(bound_names(list(tree.body)))
+    if names:
+        declarations.append(ast.Global(names=names))
+    if not body:
+        body = [ast.Pass()]
+
+    wrapper = ast.AsyncFunctionDef(
+        name=CELL_FUNCTION,
+        args=ast.arguments(
+            posonlyargs=[],
+            args=[],
+            vararg=None,
+            kwonlyargs=[],
+            kw_defaults=[],
+            kwarg=None,
+            defaults=[],
+        ),
+        body=declarations + body,
+        decorator_list=[],
+        returns=None,
+        type_comment=None,
+        type_params=[],
+    )
+    module = ast.Module(body=[wrapper], type_ignores=[])
+    ast.fix_missing_locations(module)
+    return compile(module, filename, "exec")
+
+
+def _looks_like_magic(program: str) -> bool:
+    return program.lstrip().startswith(MAGIC_PREFIXES)

ph_runtime/channel.py

@@ -0,0 +1,89 @@
+"""Newline-delimited JSON over one duplex descriptor.
+
+`json.dumps` never emits a literal newline (it escapes them inside strings), so
+a line is exactly a frame and no length prefix or escaping layer is needed.
+
+The read limit is generous because two frames are legitimately large: a program
+the model wrote, and a `snapshot` carrying `dill` payloads. It is a cap on one
+line, not an allocation.
+
+@module ph_runtime.channel
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import socket
+from typing import Any
+
+from .protocol import FD_ENV, PROTOCOL_FD
+
+__all__ = ["MAX_FRAME_BYTES", "Channel"]
+
+MAX_FRAME_BYTES = 64 * 1024 * 1024
+
+
+class Channel:
+    """The framed channel, and the only way out of this process to the host."""
+
+    def __init__(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        self._reader = reader
+        self._writer = writer
+
+    @classmethod
+    async def open(cls, fd: int | None = None) -> Channel:
+        """Attach to the inherited descriptor.
+
+        Wrapped in a `socket` object rather than opened as a file because the
+        host hands over one end of a `socketpair`: a pipe would be one-way, and
+        the guest has to both answer the host and call it.
+        """
+        if fd is None:
+            fd = int(os.environ.get(FD_ENV, PROTOCOL_FD))
+        sock = socket.socket(fileno=fd)
+        sock.setblocking(False)
+        reader, writer = await asyncio.open_connection(sock=sock, limit=MAX_FRAME_BYTES)
+        return cls(reader, writer)
+
+    async def receive(self) -> dict[str, Any] | None:
+        """The next frame, or `None` when the host has gone.
+
+        A line that will not parse is skipped rather than fatal: the host is
+        trusted for *content*, but a truncated write at shutdown should end the
+        session quietly, not with a traceback into the log.
+        """
+        while True:
+            try:
+                line = await self._reader.readline()
+            except (asyncio.IncompleteReadError, ConnectionResetError, ValueError, OSError):
+                return None
+            if not line:
+                return None
+            text = line.strip()
+            if not text:
+                continue
+            try:
+                frame = json.loads(text)
+            except ValueError:
+                continue
+            if isinstance(frame, dict):
+                return frame
+
+    def send(self, frame: dict[str, Any]) -> None:
+        """Queue one frame. Synchronous, so `print` inside a cell can call it."""
+        # A dead host is not this process's problem to report: the
+        # die-with-parent mechanism is what ends the guest (F3).
+        with contextlib.suppress(BrokenPipeError, ConnectionResetError, RuntimeError):
+            self._writer.write(json.dumps(frame, default=repr).encode("utf-8") + b"\n")
+
+    async def drain(self) -> None:
+        with contextlib.suppress(BrokenPipeError, ConnectionResetError, RuntimeError):
+            await self._writer.drain()
+
+    async def aclose(self) -> None:
+        await self.drain()
+        with contextlib.suppress(RuntimeError):
+            self._writer.close()

ph_runtime/errors.py

@@ -0,0 +1,37 @@
+"""The two failures a cell can see from a governed call, and the line between them.
+
+`ToolFailed` is the program's to handle — a timeout, a bad argument, a file that
+was not there. Catching it and trying something else is exactly right.
+
+`RunStopped` is not. It derives from `BaseException` so that `except Exception`
+does not swallow it, and the reason is C3: a program that can catch a refusal can
+route around it — retry with a different path, fall back to `subprocess`. The
+refusal ends the run, the model sees it in context, and partial state is bounded
+to one cell. A budget (C4) ends the run for the same reason: governance is per
+call, but attention is per turn.
+
+@module ph_runtime.errors
+"""
+
+from __future__ import annotations
+
+__all__ = ["RunStopped", "ToolFailed"]
+
+
+class ToolFailed(Exception):
+    """A governed call failed. Yours to handle."""
+
+    def __init__(self, name: str, message: str) -> None:
+        super().__init__(f"{name} failed: {message}")
+        self.tool_name = name
+
+
+class RunStopped(BaseException):
+    """The run is over — refused, or out of budget. Not yours to handle.
+
+    `BaseException` so `except Exception` does not swallow it — but note where
+    the *enforcement* is: a cell can still write `except BaseException`, so what
+    actually ends a refused run is the host firing its abort ladder (C3). This
+    class is the courtesy that lets a well-behaved cell unwind with a readable
+    message first.
+    """

ph_runtime/lifecycle.py

@@ -0,0 +1,89 @@
+"""Dying with the parent, per platform (F3).
+
+The OS does not do what one would hope. A parent's death does **not** kill its
+children: POSIX re-parents them to PID 1, and `atexit` never runs under
+`SIGKILL` — so a host that is hard-killed leaves a Python process holding the
+model's namespace and whatever it was doing. Each platform needs its own
+mechanism, and only one of the three lives in the guest's gift:
+
+* **Linux** — `prctl(PR_SET_PDEATHSIG, SIGKILL)`, set here because it is a
+  property of *this* process. It is armed relative to the parent that was
+  current when it was set.
+* **macOS** — no equivalent exists, so a daemon thread watches `os.getppid()`
+  and `os._exit`s when it changes. This is what prime-agent's fork-server does,
+  for this reason.
+* **Windows** — the host's job: a Job Object with `KILL_ON_JOB_CLOSE`. Nothing
+  to do here, and it is the tidiest of the three.
+
+@module ph_runtime.lifecycle
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import signal
+import sys
+import threading
+import time
+
+__all__ = ["POLL_SECONDS", "die_with_parent"]
+
+POLL_SECONDS = 1.0
+_PR_SET_PDEATHSIG = 1
+
+
+def die_with_parent() -> str:
+    """Arrange to not outlive the host. Returns the mechanism that took effect.
+
+    **There is deliberately no "am I already an orphan" check here**, and removing
+    one is what let the guest run confined at all.
+
+    It read `os.getppid() == 1` and `os._exit(0)`, guarding the window between the
+    fork and `prctl`: a host that died in it would never send the signal. The guard
+    was unnecessary and, under a PID namespace, always wrong.
+
+    *Unnecessary*, because of where this is called from. `_serve` reads the boot
+    frame **before** calling this, and returns on `None` — so reaching this line
+    means a frame was just read from the host, which is proof it was alive after
+    the spawn. A host that dies after that closes the socket, `Channel.receive`
+    returns `None`, and `serve` returns; that is the same mechanism relied on for
+    every later death, and `channel.send`'s own comment already points at it.
+
+    *Wrong*, because inside `bwrap --unshare-pid` this process's parent **is** PID
+    1 — the sandbox's init — which is the healthy arrangement rather than evidence
+    of an orphan. So the check fired on every confined start and the guest exited
+    silently, with no stderr, before sending `boot-ack`; the host could only report
+    that the runtime "exited before reporting ready". Dying with the host is the
+    sandbox's job there and it is already arranged: `bwrap` holds
+    `--die-with-parent` against the host, and the kernel tears down every process
+    in the namespace when its init goes.
+    """
+    if sys.platform.startswith("linux"):
+        if _set_pdeathsig():
+            return "pdeathsig"
+    if sys.platform == "win32":  # pragma: no cover — the host owns the Job Object
+        return "job-object"
+    _watch_parent()
+    return "getppid-poll"
+
+
+def _set_pdeathsig() -> bool:
+    try:
+        libc = ctypes.CDLL("libc.so.6", use_errno=True)
+        applied: int = libc.prctl(_PR_SET_PDEATHSIG, signal.SIGKILL, 0, 0, 0)
+    except (OSError, AttributeError):  # pragma: no cover
+        return False
+    return applied == 0
+
+
+def _watch_parent() -> None:
+    original = os.getppid()
+
+    def watch() -> None:  # pragma: no cover — timing-dependent
+        while True:
+            time.sleep(POLL_SECONDS)
+            if os.getppid() != original:
+                os._exit(0)
+
+    threading.Thread(target=watch, name="ph-parent-watch", daemon=True).start()

ph_runtime/limits.py

@@ -0,0 +1,103 @@
+"""Resource limits, applied in the child before it reports ready (D3).
+
+Two of the three are straightforward. The CPU limit is not, and the reason is
+worth stating because it changes what the number *means*:
+
+**`RLIMIT_CPU` is cumulative over the process, and this process is persistent.**
+Setting it once to `cpu_seconds` would give the whole kernel one budget for its
+whole life — so the fortieth cell in a session would die on a limit the first
+cell nearly spent. Re-arming it at each run, from the CPU already consumed,
+turns the cumulative counter into a per-cell budget, which is what the caller
+means by `cpu_seconds` and what the gate tests.
+
+Exceeding it raises `CpuBudgetExceeded`, which derives from `BaseException` on
+purpose: like a denial (C3), a budget is not the program's to catch. A cell that
+could `except Exception` its way past the limit would make the limit advisory.
+
+@module ph_runtime.limits
+"""
+
+from __future__ import annotations
+
+import contextlib
+import math
+import signal
+from typing import Any
+
+__all__ = ["CpuBudgetExceeded", "apply_limits", "arm_cpu_budget", "cpu_seconds_used"]
+
+
+class CpuBudgetExceeded(BaseException):
+    """The cell used its CPU budget. Not an `Exception`: not catchable by policy."""
+
+
+try:
+    import resource
+except ImportError:  # pragma: no cover — Windows has no `resource` module
+    resource = None  # type: ignore[assignment]
+
+
+def cpu_seconds_used() -> float:
+    """CPU seconds this process has consumed, user + system."""
+    if resource is None:  # pragma: no cover
+        import time
+
+        return time.process_time()
+    usage = resource.getrusage(resource.RUSAGE_SELF)
+    return float(usage.ru_utime + usage.ru_stime)
+
+
+def apply_limits(*, address_space_bytes: int) -> dict[str, Any]:
+    """Apply the process-lifetime limits and report what took effect.
+
+    Reported rather than assumed: a hard limit lower than the request cannot be
+    raised back, so the host logs the number in force instead of the number it
+    asked for.
+    """
+    applied: dict[str, Any] = {"addressSpaceBytes": None, "cpu": "per-run"}
+    if resource is None:  # pragma: no cover — Windows uses a Job Object instead
+        applied["addressSpaceBytes"] = "job-object"
+        return applied
+    if address_space_bytes > 0:
+        soft, hard = resource.getrlimit(resource.RLIMIT_AS)
+        target = (
+            address_space_bytes
+            if hard == resource.RLIM_INFINITY
+            else min(address_space_bytes, hard)
+        )
+        try:
+            resource.setrlimit(resource.RLIMIT_AS, (target, hard))
+            applied["addressSpaceBytes"] = target
+        except (ValueError, OSError):
+            # The limit is *not* in force, and the report must say so in a number
+            # the host can read. macOS refuses `RLIMIT_AS` outright (`ValueError:
+            # current limit exceeds maximum limit`), and this branch used to report
+            # `soft` — which there is `RLIM_INFINITY`, 2**63-1, above the codec's
+            # lossless-integer bound. The host dropped the whole `boot-ack` as
+            # unreadable and waited out `boot_timeout` on every kernel start
+            # (measured 2026-09-07: 60 s of silence, then "did not report ready").
+            # `None` is what the report already means by "no limit"; a finite soft
+            # limit that was already in force is still the number in force.
+            applied["addressSpaceBytes"] = None if soft == resource.RLIM_INFINITY else soft
+    return applied
+
+
+def _on_sigxcpu(_signum: int, _frame: object) -> None:
+    raise CpuBudgetExceeded("this cell used its CPU budget")
+
+
+def arm_cpu_budget(cpu_seconds: int) -> None:
+    """Give the *next* run `cpu_seconds` of CPU, from whatever is spent so far."""
+    if resource is None or cpu_seconds <= 0:  # pragma: no cover
+        return
+    signal.signal(signal.SIGXCPU, _on_sigxcpu)
+    # `ceil`, not `int`: flooring the CPU already spent hands the next cell less
+    # than `cpu_seconds` — a bomb that burned 1.9s floors to 1, so a budget of 1
+    # leaves 0.1s and the *next* trivial cell dies on the previous one's spend.
+    used = math.ceil(cpu_seconds_used())
+    soft = used + cpu_seconds
+    _, hard = resource.getrlimit(resource.RLIMIT_CPU)
+    if hard != resource.RLIM_INFINITY:
+        soft = min(soft, hard)
+    with contextlib.suppress(ValueError, OSError):  # pragma: no cover
+        resource.setrlimit(resource.RLIMIT_CPU, (soft, hard))