agentic-runner 2.6.0__py3-none-any.whl

agentic_runner/workers/_runtime_support.py

@@ -0,0 +1,388 @@
+"""Runtime-neutral machinery shared by Agent Runtimes.
+
+The subprocess spawn (with process-group kill on timeout/cancel), workspace-under-root
+validation, command hashing, and byte-bounding here are identical for every CLI runtime
+(Codex, Claude Code, ...). Each runtime keeps its own secret-redaction patterns, since
+the secrets it must scrub differ; this module holds only what is genuinely shared.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import os
+import re
+import signal
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from agentic_runner.callback import CALLBACK_SOCKET_ENV, CALLBACK_TOKEN_ENV
+from agentic_runner.egress import EGRESS_ENV_NAMES
+from agentic_runner.llm_proxy import PROXY_ENV_NAMES
+from agentic_runner.workers.command_policy import CommandPolicy, evaluate_command_policy
+from agentic_runner.workers.contract_isolation import DirectiveSandbox
+
+# Names no caller may set on a Directive's environment, whatever a Runner Hook exported
+# (PRD issue 45). Each is a line the Runner itself draws: the per-Contract harness root
+# and HOME (ADR-0015 §4), the TMPDIR inside the Contract's tree, the PATH the harness
+# binary resolves on, the attempt's own callback socket and bearer, and the LLM proxy's
+# endpoint and bearer (PRD issue 43), and the attempt's egress proxy (PRD issue 58). An
+# `environment` hook that could rewrite them would move the Contract's config root
+# somewhere another Contract can read, hand the Agent a socket and bearer of its own
+# choosing, point the Agent's traffic at an endpoint that meters nothing and is charged to
+# the funder anyway, or route it round the Profile's egress allow-list.
+RESERVED_DIRECTIVE_ENV: Final[frozenset[str]] = frozenset(
+    {
+        "HOME",
+        "PATH",
+        "TMPDIR",
+        "CODEX_HOME",
+        "CLAUDE_CONFIG_DIR",
+        "ANTHROPIC_API_KEY",
+        CALLBACK_SOCKET_ENV,
+        CALLBACK_TOKEN_ENV,
+        *PROXY_ENV_NAMES,
+        *EGRESS_ENV_NAMES,
+    }
+)
+
+
+# The callback pair and the proxy pair are minted by the Runner and travel on this same
+# channel, so they are the part of the reserved set that may land here. A *hook* is
+# stopped from claiming those names earlier and elsewhere — `hooks._read_env_file` drops
+# them as it reads the exports — which keeps one rule in each place instead of one
+# conditional in both.
+_EXTRA_ENV_DENYLIST: Final[frozenset[str]] = RESERVED_DIRECTIVE_ENV - {
+    CALLBACK_SOCKET_ENV,
+    CALLBACK_TOKEN_ENV,
+    *PROXY_ENV_NAMES,
+    *EGRESS_ENV_NAMES,
+}
+
+
+# Provider keys a runtime may otherwise put in the child environment. Dropped whenever
+# the attempt routes through the Runner's LLM proxy instead.
+_PROVIDER_KEY_ENV: Final[frozenset[str]] = frozenset({"ANTHROPIC_API_KEY", "OPENAI_API_KEY"})
+
+
+def apply_extra_env(env: dict[str, str], extra: Iterable[tuple[str, str]]) -> dict[str, str]:
+    """Merge one attempt's extra environment into a Directive's, minus the reserved names.
+
+    Where the attempt carries an LLM proxy endpoint (PRD issue 43), the runtime's own
+    provider key is dropped from the child environment rather than left beside it: the
+    whole point of the relocated proxy is that the subprocess holds the attempt's bearer
+    and no provider key (ADR-0011 §9), and a key still in the env is a way around the
+    metering point. Done here because both runtimes route through this one call.
+    """
+
+    admitted = {name: value for name, value in extra if name not in _EXTRA_ENV_DENYLIST}
+    if PROXY_ENV_NAMES & set(admitted):
+        for name in _PROVIDER_KEY_ENV:
+            env.pop(name, None)
+    env.update(admitted)
+    return env
+
+
+@dataclass(frozen=True, slots=True)
+class SubprocessResult:
+    exit_code: int
+    stdout: str
+    stderr: str
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+
+
+AsyncSubprocessRunner = Callable[
+    [list[str], Path, dict[str, str], str | None, int, int], Awaitable[SubprocessResult]
+]
+
+
+async def run_subprocess_exec(
+    *,
+    argv: list[str],
+    cwd: Path,
+    env: dict[str, str],
+    stdin: str | None,
+    timeout_seconds: int,
+    output_limit_bytes: int,
+    sandbox: DirectiveSandbox | None = None,
+) -> SubprocessResult:
+    process = await asyncio.create_subprocess_exec(
+        *argv,
+        cwd=cwd,
+        env=env,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        start_new_session=True,
+        **({} if sandbox is None else sandbox.spawn_kwargs()),
+    )
+    try:
+        stdout_bytes, stderr_bytes, stdout_truncated, stderr_truncated = await asyncio.wait_for(
+            _collect_process_output(process, stdin=stdin, output_limit_bytes=output_limit_bytes),
+            timeout=timeout_seconds,
+        )
+    except TimeoutError:
+        await _terminate_process_tree(process)
+        raise
+    except asyncio.CancelledError:
+        await _terminate_process_tree(process)
+        raise
+
+    return SubprocessResult(
+        exit_code=process.returncode or 0,
+        stdout=stdout_bytes.decode(errors="replace"),
+        stderr=stderr_bytes.decode(errors="replace"),
+        stdout_truncated=stdout_truncated,
+        stderr_truncated=stderr_truncated,
+    )
+
+
+async def _collect_process_output(
+    process: asyncio.subprocess.Process,
+    *,
+    stdin: str | None,
+    output_limit_bytes: int,
+) -> tuple[bytes, bytes, bool, bool]:
+    if process.stdin is not None:
+        with contextlib.suppress(BrokenPipeError, ConnectionResetError):
+            if stdin is not None:
+                process.stdin.write(stdin.encode())
+                await process.stdin.drain()
+            process.stdin.close()
+            await process.stdin.wait_closed()
+
+    stdout_task = asyncio.create_task(_read_stream_limited(process.stdout, output_limit_bytes))
+    stderr_task = asyncio.create_task(_read_stream_limited(process.stderr, output_limit_bytes))
+    try:
+        await process.wait()
+        stdout_bytes, stdout_truncated = await stdout_task
+        stderr_bytes, stderr_truncated = await stderr_task
+    except BaseException:
+        stdout_task.cancel()
+        stderr_task.cancel()
+        raise
+    return stdout_bytes, stderr_bytes, stdout_truncated, stderr_truncated
+
+
+async def _read_stream_limited(
+    stream: asyncio.StreamReader | None,
+    limit_bytes: int,
+) -> tuple[bytes, bool]:
+    """Read a child's stream, bounded to the *last* ``limit_bytes``.
+
+    Keeping the head instead of the tail here silently dropped Codex's ``turn.completed``
+    and Claude Code's ``result`` message on any Directive whose output crossed the limit —
+    both harnesses put their final, JSONL/JSON usage event at the end of stdout
+    (``harness_usage.py``), and the head-bounded runtime evidence layer (``bound_text_tail``
+    in ``codex_runtime.py``/``claude_runtime.py``) already assumed the tail was what
+    survived. There is nothing left for a caller-side tail-bound to recover once the head
+    is what got kept here, so the read itself must keep the tail.
+    """
+
+    if stream is None:
+        return b"", False
+
+    tail = bytearray()
+    total_bytes = 0
+    while True:
+        chunk = await stream.read(4096)
+        if not chunk:
+            break
+        total_bytes += len(chunk)
+        tail.extend(chunk)
+        if len(tail) > limit_bytes:
+            del tail[: len(tail) - limit_bytes]
+    return bytes(tail), total_bytes > limit_bytes
+
+
+async def _terminate_process_tree(process: asyncio.subprocess.Process) -> None:
+    if process.returncode is not None:
+        return
+    with contextlib.suppress(ProcessLookupError, PermissionError):
+        os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+    if process.returncode is None:
+        with contextlib.suppress(ProcessLookupError):
+            process.kill()
+    with contextlib.suppress(TimeoutError):
+        await asyncio.wait_for(process.wait(), timeout=2)
+
+
+def is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def workspace_id(workspace_path: Path, workspace_root: Path) -> str:
+    return workspace_path.relative_to(workspace_root).as_posix()
+
+
+def hash_command(argv: list[str]) -> str:
+    return hashlib.sha256("\0".join(argv).encode()).hexdigest()
+
+
+def redact_match(match: re.Match[str]) -> str:
+    if match.lastindex and match.lastindex >= 3:
+        return f"{match.group(1)}[REDACTED]{match.group(3)}"
+    if match.lastindex and match.lastindex >= 2:
+        return f"{match.group(1)}[REDACTED]"
+    return "[REDACTED]"
+
+
+def bound_text(value: str, limit_bytes: int, notes: list[str], label: str) -> str:
+    encoded = value.encode()
+    if len(encoded) <= limit_bytes:
+        return value
+
+    notes.append(f"{label} truncated to {limit_bytes} bytes")
+    return encoded[:limit_bytes].decode(errors="ignore")
+
+
+def bound_text_tail(value: str, limit_bytes: int, notes: list[str], label: str) -> str:
+    """Like ``bound_text`` but keeps the *end* of the text — where test runners put
+    the failure summary and tracebacks that a fix Directive actually needs."""
+    encoded = value.encode()
+    if len(encoded) <= limit_bytes:
+        return value
+
+    notes.append(f"{label} truncated to last {limit_bytes} bytes")
+    return encoded[-limit_bytes:].decode(errors="ignore")
+
+
+def command_policy_refusal(
+    *,
+    argv: list[str],
+    program: str,
+    workspace_path: Path,
+    workspace_root: Path,
+    base_branch: str,
+    work_branch: str,
+) -> str | None:
+    """The Agent Runtime Profile's sandbox floor, applied to every Directive (ADR-0011 §12).
+
+    The subprocess the Runner is about to spawn is checked against
+    ``workers/command_policy.py`` before it runs: outside the grant model, not attenuable by
+    the user, and re-checked per Directive rather than once at configuration time, because
+    the worker settings that build the argv can change under a running worker. Returns the
+    refusal reason, or None when the floor allows the spawn.
+    """
+
+    decision = evaluate_command_policy(
+        argv=argv,
+        cwd=workspace_path,
+        workspace_root=workspace_root,
+        base_branch=base_branch,
+        work_branch=work_branch,
+        policy=CommandPolicy(runtime_program=program),
+    )
+    return None if decision.allowed else decision.reason
+
+
+# Process-global strong references to detached launches' background drain tasks. A
+# request/activity-scoped call is otherwise the only strong root, and task -> coroutine ->
+# process is a cycle the garbage collector can reap once the caller returns (the event
+# loop keeps only weak references to tasks) -- rooting them here keeps a detached child
+# draining and reaped for as long as it runs.
+_DETACHED_LAUNCH_DRAINS: set[asyncio.Task[None]] = set()
+
+
+async def run_subprocess_launch_and_detach(
+    *,
+    argv: list[str],
+    cwd: Path,
+    env: dict[str, str],
+    is_prompt_complete: Callable[[str], bool],
+    prompt_timeout_seconds: float,
+    output_limit_bytes: int,
+    sandbox: DirectiveSandbox | None = None,
+) -> str:
+    """Spawn a long-running interactive CLI, return once its opening prompt is complete.
+
+    Unlike :func:`run_subprocess_exec` (run-to-completion), a device-code sign-in prints a
+    verification URL and one-time code and then *blocks*, polling the vendor until the
+    operator finishes the browser flow or the code expires (research/29). The caller needs
+    only the prompt, not that wait: reading it in an ``execute_workflow`` call held the
+    HTTP request (and, with no override, a 60s client timeout) open for however long the
+    operator took, and the funder learned the URL/code only after the whole wait finished
+    (PRD issue 31 review). This reads stdout only until ``is_prompt_complete`` accepts it,
+    then detaches the process -- draining its pipes in the background so it never blocks on
+    a full buffer -- so a later, separate read can check whether it finished.
+    """
+
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=cwd,
+            env=env,
+            stdin=asyncio.subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            start_new_session=True,
+            **({} if sandbox is None else sandbox.spawn_kwargs()),
+        )
+    except OSError as error:
+        raise RuntimeError(f"process failed to start: {error.__class__.__name__}") from None
+
+    if process.stdout is None:
+        await _terminate_process_tree(process)
+        raise RuntimeError("process stdout stream was unavailable")
+
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + prompt_timeout_seconds
+    buffer = bytearray()
+    try:
+        while True:
+            remaining = deadline - loop.time()
+            if remaining <= 0:
+                raise TimeoutError("device-login prompt did not appear before the timeout")
+            try:
+                chunk = await asyncio.wait_for(process.stdout.read(4096), timeout=remaining)
+            except TimeoutError:
+                raise TimeoutError(
+                    "device-login prompt did not appear before the timeout"
+                ) from None
+            if not chunk:
+                raise RuntimeError(
+                    f"process exited before printing its prompt (code {process.returncode})"
+                )
+            buffer.extend(chunk)
+            if len(buffer) > output_limit_bytes:
+                raise RuntimeError("process output exceeded the configured byte limit")
+            text = buffer.decode("utf-8", errors="replace")
+            if is_prompt_complete(text):
+                _detach(process)
+                return text
+    except BaseException:
+        await _terminate_process_tree(process)
+        raise
+
+
+def _detach(process: asyncio.subprocess.Process) -> None:
+    # Static target (no closure over caller state) so the drain coroutine roots only
+    # through the module-level set below, not through whatever scheduled this launch.
+    task = asyncio.ensure_future(_drain_detached(process))
+    _DETACHED_LAUNCH_DRAINS.add(task)
+    task.add_done_callback(_DETACHED_LAUNCH_DRAINS.discard)
+
+
+async def _drain_detached(process: asyncio.subprocess.Process) -> None:
+    # Best-effort: keeps the detached child's pipes empty so it never blocks on a full
+    # buffer, then reaps it. A failure here must never surface into a caller that already
+    # returned the prompt.
+    try:
+        streams = [s for s in (process.stdout, process.stderr) if s is not None]
+        await asyncio.gather(*(_drain_stream(stream) for stream in streams))
+        await process.wait()
+    except Exception:  # noqa: BLE001 - best-effort background reap, see docstring above
+        return
+
+
+async def _drain_stream(stream: asyncio.StreamReader) -> None:
+    while await stream.read(8192):
+        continue

agentic_runner/workers/agent_runtime.py

@@ -0,0 +1,93 @@
+"""The AgentRuntime port: the single-turn contract every runtime implements.
+
+Temporal owns the Ralph Loop (ADR-0007), so a runtime never runs its own loop — it
+executes exactly one Directive and returns the result. This module defines the
+runtime-neutral port and the data that crosses it, so a second runtime (Claude Code,
+issue 11) can be added behind the same seam as Codex (ADR-0006).
+
+Concrete runtimes are siblings of this module in ``agentic_runner.workers`` and are
+injected into the activity adapter. They must never enter the workflow import graph (the
+determinism sandbox); the deterministic workflow only ever invokes them by activity name.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from agentic_runner.workers.contract_isolation import DirectiveSandbox
+from agentic_runner.workers.mcp_config import McpServerEntry
+
+
+class AuthModel(StrEnum):
+    """How a runtime authenticates. Declared per-runtime so an unattended Persona can be
+    placed on stable API-key auth instead of an expiring browser session (ADR-0006)."""
+
+    DEVICE_LOGIN = "device_login"
+    API_KEY = "api_key"
+
+
+@dataclass(frozen=True, slots=True)
+class DirectiveRequest:
+    """The input to one Directive: a single runtime turn in a prepared workspace."""
+
+    workspace_path: Path
+    prompt: str
+    base_branch: str
+    work_branch: str
+    # Which Contract's uid this turn runs as, where its harness config root is, and the
+    # floor it may not exceed (ADR-0015 §1). None only where the caller built no
+    # isolation at all (unit fakes); the composition root always supplies one.
+    sandbox: DirectiveSandbox | None = None
+    # The attempt's callback socket and bearer, plus whatever the `environment` Runner
+    # Hook exported (PRD issue 45). Pairs rather than a mapping so the request stays
+    # frozen; every runtime merges them through `_runtime_support.apply_extra_env`, which
+    # drops the names the Runner reserves for itself.
+    extra_env: tuple[tuple[str, str], ...] = ()
+    # The MCP servers the Agent's Effective Grant lets this Directive have (PRD issue
+    # 58). ``None`` -- no server is bound to the Work Record's Product -- leaves the CLI's
+    # own config untouched, so a Product without MCP runs byte-identically to before;
+    # ``()`` is "servers are bound, none granted", which still has to be said to the CLI
+    # so nothing ungranted is loaded from anywhere else.
+    mcp_servers: tuple[McpServerEntry, ...] | None = None
+    # The destinations this Directive may reach (the Profile's list plus what the Runner
+    # added), enforced by the attempt's egress proxy. Empty: no Profile list, so the
+    # runtime keeps its own network posture.
+    egress_allow_list: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DirectiveEvidence:
+    """Bounded, redacted record of one Directive, safe for control-plane storage."""
+
+    workspace_id: str
+    base_branch: str
+    work_branch: str
+    command_hash: str
+    guard_mode: str
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class DirectiveResult:
+    """The outcome of one Directive. ``exit_code`` 0 is success; a guard refusal is
+    signalled by ``exit_code`` 126 and an ``evidence.guard_mode`` starting with
+    ``"refused"`` — the discriminator the Ralph Loop branches on."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    error: str
+    command_hash: str
+    evidence: DirectiveEvidence
+
+
+@runtime_checkable
+class AgentRuntime(Protocol):
+    """The pluggable engine an Agent uses to execute one Directive per step."""
+
+    auth_model: AuthModel
+
+    async def execute_directive(self, request: DirectiveRequest) -> DirectiveResult: ...