agentic-runner 2.6.0__py3-none-any.whl

agentic_runner/mcp.py

@@ -0,0 +1,342 @@
+"""MCP config assembly and Runner-hosted MCP servers (PRD issue 58; 05, 17 A4, ADR-0015 §3).
+
+**Assembly** is the seam ``mcp:<server>`` lands with (ADR-0011 §3, §8): per Directive,
+each registry row bound to the Work Record's Product is decided against the Agent's
+Effective Grant (:func:`agentic_runner_contracts.grants.decide_mcp_server`) and only a
+granted server reaches the CLI's config. ``confirm`` asks the owner *before* the server is
+written -- MCP has no per-call seam inside the CLI, so config assembly is the narrowest
+place a confirmation can bite.
+
+**Placement** follows 17 A4. A stdio server with no credential is written as a command:
+the CLI spawns it, so it runs as the Contract's uid, a grandchild of the Runner, with the
+Directive's own credential-free environment. A row naming a Credential Reference is
+**Runner-hosted**: :class:`RunnerHostedServer` spawns it as the Runner's own uid with the
+value in its env, and exposes it to the CLI as Streamable HTTP on loopback behind the
+attempt's bearer -- the Agent talks to the server and never holds what the server holds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+from collections.abc import Awaitable, Callable, Collection, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from types import TracebackType
+from typing import Any, Final
+
+from agentic_runner.tiny_http import bearer_matches, read_request, response_head, write_json
+from agentic_runner.workers.mcp_config import McpServerEntry
+from agentic_runner_contracts.grants import (
+    Decision,
+    GrantSnapshot,
+    McpServerDecision,
+    decide_mcp_server,
+)
+from agentic_runner_contracts.runner_registration import ToolServerHealth
+from agentic_runner_contracts.runtime_context import McpServerSpec
+
+__all__ = [
+    "MCP_ASSEMBLY_SOURCE",
+    "McpPlan",
+    "RunnerHostedServer",
+    "Spawner",
+    "ToolServerHealthLog",
+    "entry_for",
+    "plan_mcp",
+]
+
+# One Evidence Event per config assembly: granted, withheld and why (PRD issue 58).
+MCP_ASSEMBLY_SOURCE: Final[str] = "runner.mcp_config_assembled"
+
+# The one path a Runner-hosted server answers on, as Streamable HTTP's single endpoint.
+MCP_PATH: Final[str] = "/mcp"
+
+# What a Runner-hosted server inherits from the Runner besides its credential. A
+# credential-bearing child must not also inherit the Runner's own environment (its
+# Agent Token, a git token): only what a program needs to start.
+_HOSTED_ENV_ALLOWLIST: Final[tuple[str, ...]] = ("PATH", "HOME", "LANG", "TZ")
+_DEFAULT_CALL_TIMEOUT_SECONDS: Final[float] = 300.0
+# The heartbeat's own bound on `tool_servers`.
+_HEALTH_MAX: Final[int] = 64
+
+Spawner = Callable[..., Awaitable[asyncio.subprocess.Process]]
+
+
+@dataclass(frozen=True)
+class McpPlan:
+    """What one Directive's config assembly decided, before anything is started."""
+
+    granted: tuple[tuple[McpServerSpec, McpServerDecision], ...] = ()
+    withheld: tuple[tuple[McpServerSpec, McpServerDecision, str], ...] = ()
+    to_confirm: tuple[tuple[McpServerSpec, McpServerDecision], ...] = ()
+
+    def evidence(self, *, egress_allow_list: Sequence[str] = ()) -> dict[str, object]:
+        return {
+            "event": "mcp.config_assembled",
+            "granted": [
+                {**decision.evidence(), "runner_hosted": spec.credential_reference is not None}
+                for spec, decision in self.granted
+            ],
+            "withheld": [
+                {**decision.evidence(), "withheld_because": why}
+                for _, decision, why in self.withheld
+            ],
+            "egress_allow_list": list(egress_allow_list),
+        }
+
+
+def plan_mcp(
+    snapshot: GrantSnapshot,
+    servers: Sequence[McpServerSpec],
+    *,
+    consented: Collection[str] = (),
+    declined: Collection[str] = (),
+) -> McpPlan:
+    """Decide every bound server against the Effective Grant.
+
+    ``consented`` / ``declined`` are the ``mcp:<server>`` names the owner has already
+    answered for this step; anything else that evaluates ``confirm`` is left in
+    ``to_confirm`` for the caller to ask about before a single server is started.
+    """
+
+    granted: list[tuple[McpServerSpec, McpServerDecision]] = []
+    withheld: list[tuple[McpServerSpec, McpServerDecision, str]] = []
+    to_confirm: list[tuple[McpServerSpec, McpServerDecision]] = []
+    for spec in servers:
+        decision = decide_mcp_server(snapshot, server=spec.slug, tools=spec.tools)
+        confirm = decision.decision is Decision.CONFIRM
+        if decision.decision is Decision.ALLOW or (confirm and decision.verb in consented):
+            granted.append((spec, decision))
+        elif confirm and decision.verb in declined:
+            withheld.append((spec, decision, "owner_declined"))
+        elif confirm:
+            to_confirm.append((spec, decision))
+        else:
+            withheld.append((spec, decision, "denied"))
+    return McpPlan(granted=tuple(granted), withheld=tuple(withheld), to_confirm=tuple(to_confirm))
+
+
+def entry_for(
+    spec: McpServerSpec, *, hosted_url: str | None = None, bearer_env: str | None = None
+) -> McpServerEntry:
+    """The CLI's view of one granted server: its command, or the URL to call."""
+
+    if hosted_url is not None:
+        return McpServerEntry(
+            slug=spec.slug, url=hosted_url, bearer_token_env=bearer_env, required=spec.required
+        )
+    if spec.transport == "streamable_http":
+        return McpServerEntry(slug=spec.slug, url=str(spec.config["url"]), required=spec.required)
+    return McpServerEntry(
+        slug=spec.slug,
+        command=str(spec.config["command"]),
+        args=tuple(str(arg) for arg in _list(spec.config.get("args"))),
+        required=spec.required,
+    )
+
+
+def _list(value: object) -> list[object]:
+    return list(value) if isinstance(value, list) else []
+
+
+@dataclass
+class ToolServerHealthLog:
+    """The latest start of each Runner-hosted Tool Server, for the heartbeat (issue 29).
+
+    Keyed by slug, not by Work Record: it is a fact about this host, like the load and
+    the slots, and a later Directive's start of the same server replaces the earlier one.
+    """
+
+    clock: Callable[[], datetime] = field(default=lambda: datetime.now(UTC))
+    _latest: dict[str, ToolServerHealth] = field(default_factory=dict)
+
+    def record(self, slug: str, *, started: bool, at: datetime) -> None:
+        self._latest[slug] = ToolServerHealth(slug=slug, started=started, last_started_at=at)
+
+    def latest(self) -> list[ToolServerHealth]:
+        newest = sorted(self._latest.values(), key=lambda entry: entry.last_started_at)
+        return newest[-_HEALTH_MAX:]
+
+
+class RunnerHostedServer:
+    """One credentialed stdio server, spawned by the Runner and bridged to loopback HTTP.
+
+    The Runner speaks stdio JSON-RPC to the child and answers the CLI's Streamable HTTP
+    POSTs on ``127.0.0.1:<ephemeral>/mcp``, one request at a time, only for a caller
+    presenting the attempt's bearer. The whole bridge dies with the attempt, which is
+    what bounds the bearer (ADR-0011 §9).
+
+    No SSE stream: a request is answered with one ``application/json`` body, a
+    notification with ``202`` -- the subset of the transport both CLIs use for tool calls.
+    """
+
+    def __init__(
+        self,
+        spec: McpServerSpec,
+        *,
+        credential_env: Mapping[str, str],
+        token: str,
+        spawner: Spawner | None = None,
+        host: str = "127.0.0.1",
+        call_timeout_seconds: float = _DEFAULT_CALL_TIMEOUT_SECONDS,
+        health: ToolServerHealthLog | None = None,
+    ) -> None:
+        self.spec = spec
+        self._credential_env = dict(credential_env)
+        self._token = token
+        self._spawner: Spawner = spawner or asyncio.create_subprocess_exec
+        self._host = host
+        self._timeout = call_timeout_seconds
+        self._process: asyncio.subprocess.Process | None = None
+        self._server: asyncio.Server | None = None
+        self._lock = asyncio.Lock()
+        self._port = 0
+        self._health = health
+        self._started_at: datetime | None = None
+        self._reported = False
+
+    @property
+    def url(self) -> str:
+        return f"http://{self._host}:{self._port}{MCP_PATH}"
+
+    async def __aenter__(self) -> RunnerHostedServer:
+        env = {name: os.environ[name] for name in _HOSTED_ENV_ALLOWLIST if name in os.environ}
+        env.update(self._credential_env)
+        if self._health is not None:
+            self._started_at = self._health.clock()
+        # The Runner's own uid: no `user=` / `group=` here, deliberately. The credential
+        # is the Runner's to hold, and the Contract's uid must not be able to read the
+        # process that holds it (17 A4).
+        try:
+            self._process = await self._spawner(
+                str(self.spec.config["command"]),
+                *(str(arg) for arg in _list(self.spec.config.get("args"))),
+                env=env,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+                start_new_session=True,
+            )
+        except BaseException:
+            self._report(started=False)
+            raise
+        try:
+            self._server = await asyncio.start_server(self._serve, host=self._host, port=0)
+        except BaseException:
+            self._report(started=False)
+            await self._stop_process()
+            raise
+        self._port = int(self._server.sockets[0].getsockname()[1])
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._server is not None:
+            self._server.close()
+            with contextlib.suppress(Exception):
+                await self._server.wait_closed()
+        # No call reached it: it came up if it was still running when the attempt ended.
+        process = self._process
+        self._report(started=process is not None and process.returncode is None)
+        await self._stop_process()
+
+    def _report(self, *, started: bool) -> None:
+        """Record this start once: the first call's outcome, else the state at exit."""
+
+        if self._health is None or self._started_at is None or self._reported:
+            return
+        self._reported = True
+        self._health.record(self.spec.slug, started=started, at=self._started_at)
+
+    async def _stop_process(self) -> None:
+        process = self._process
+        if process is None or process.returncode is not None:
+            return
+        with contextlib.suppress(ProcessLookupError):
+            process.kill()
+        with contextlib.suppress(TimeoutError, ProcessLookupError):
+            await asyncio.wait_for(process.wait(), timeout=5)
+
+    async def _serve(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            request = await read_request(reader)
+            if isinstance(request, tuple):
+                await write_json(writer, request[0], request[1])
+                return
+            if not bearer_matches(request.authorization, self._token):
+                await write_json(writer, 401, {"detail": "the attempt bearer is required"})
+                return
+            if request.target.split("?", 1)[0] != MCP_PATH:
+                await write_json(writer, 404, {"detail": "not found"})
+                return
+            if request.method != "POST":
+                await write_json(writer, 405, {"detail": "only POST is served"})
+                return
+            try:
+                message = json.loads(request.body)
+            except ValueError:
+                await write_json(writer, 400, {"detail": "the body is not JSON"})
+                return
+            if not isinstance(message, dict):
+                await write_json(writer, 400, {"detail": "one JSON-RPC message per request"})
+                return
+            try:
+                reply = await self._call(message)
+            except (TimeoutError, ConnectionError, RuntimeError):
+                self._report(started=False)
+                raise
+            if reply is None:
+                writer.write(response_head(202, content_type="application/json", content_length=0))
+                with contextlib.suppress(ConnectionError):
+                    await writer.drain()
+                return
+            # Only an answer proves the server up: a notification is a write to a pipe,
+            # which a dead child's buffer can still take.
+            self._report(started=True)
+            await write_json(writer, 200, reply)
+        except TimeoutError:
+            await write_json(writer, 504, {"detail": "the MCP server did not answer in time"})
+        except (ConnectionError, RuntimeError):
+            await write_json(writer, 502, {"detail": "the MCP server is not running"})
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+
+    async def _call(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        process = self._process
+        if process is None or process.stdin is None or process.stdout is None:
+            raise RuntimeError("the MCP server is not running")
+        stdout = process.stdout
+        expects_reply = "method" in message and "id" in message
+        async with self._lock:
+            process.stdin.write(json.dumps(message).encode() + b"\n")
+            await process.stdin.drain()
+            if not expects_reply:
+                return None
+
+            async def read_reply() -> dict[str, Any]:
+                while True:
+                    line = await stdout.readline()
+                    if not line:
+                        raise ConnectionError("the MCP server closed its stdout")
+                    try:
+                        candidate = json.loads(line)
+                    except ValueError:
+                        continue
+                    # Its own notifications and log lines are not this call's answer.
+                    if (
+                        isinstance(candidate, dict)
+                        and "method" not in candidate
+                        and candidate.get("id") == message["id"]
+                    ):
+                        return candidate
+
+            return await asyncio.wait_for(read_reply(), timeout=self._timeout)

agentic_runner/message_store.py

@@ -0,0 +1,341 @@
+"""The per-Work-Record Message store and the wake signal (PRD issue 52, map ticket 10).
+
+Where Channel bodies live. Decision 10 held, stricter than 13: Directive payloads cross
+into the control plane unencrypted in Release 1, **Channel bodies never do**. One
+Conversation per Work Record, append-only, keyed by Channel; owned by the Runner
+*process* and reached by the Agent subprocess only through its attempt socket
+(``agentic-runner message send | list``), so a Contract's uid never reads the file
+(17 A1). The tree therefore lives under the Runner's own state directory -- never under
+the Contract's uid-owned Workspace tree -- with ``0700`` directories and ``0600`` files.
+
+Lifetime: kept for the Organisation's one retention period and dropped by the same
+sweep that deletes Workspaces. Contract termination **seals** the Contract's stores: the
+org retains, the user loses access, the marker carries the state so a pull-through can
+say why it was refused.
+
+Three things leave this module, and this docstring is where the partition is stated:
+``MessageMetadata`` as Evidence (no body), :data:`PENDING_MESSAGES_SIGNAL` as a Temporal
+signal (ids and a count), and a ``TranscriptDelivery`` over the Runner's signed stream
+when the liable user asks. Nothing else reads a body.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Final, Literal, Protocol
+from uuid import UUID, uuid4
+
+from temporalio.client import Client
+
+from agentic_runner_contracts.channel_messages import (
+    PENDING_MESSAGES_SIGNAL,
+    MessageEnvelope,
+    MessageKind,
+    MessageReference,
+    PendingMessagesSignal,
+    ReferenceKind,
+    TranscriptDelivery,
+    TranscriptRequest,
+)
+from agentic_runner_contracts.public_metadata import OUTCOME_KINDS, workflow_id
+
+__all__ = [
+    "MESSAGES_DIR",
+    "SEALED_MARKER",
+    "MessageStore",
+    "TemporalWorkflowSignaller",
+    "WorkflowSignaller",
+]
+
+MESSAGES_DIR: Final = "messages"
+SEALED_MARKER: Final = "SEALED"
+_DIR_MODE: Final = 0o700
+_FILE_MODE: Final = 0o600
+
+
+class WorkflowSignaller(Protocol):
+    async def signal(self, pending: PendingMessagesSignal) -> None:
+        """Wake the Work Record's workflow with ids and a count, nothing else."""
+
+
+class TemporalWorkflowSignaller:
+    """The wake signal over the Runner's own namespace connection.
+
+    A Runner polls exactly one namespace -- its Organisation's (map ticket 15 §2) -- and
+    the client it polls with is the one this sends on, so the signal cannot land in any
+    other Organisation's namespace by construction. The workflow id is built by the
+    Public Metadata builder like every Temporal-visible name (ADR-0010 §6).
+    """
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    async def signal(self, pending: PendingMessagesSignal) -> None:
+        handle = self._client.get_workflow_handle(
+            workflow_id(outcome_kind=OUTCOME_KINDS[0], work_record_id=UUID(pending.work_record_id))
+        )
+        await handle.signal(PENDING_MESSAGES_SIGNAL, pending)
+
+
+class MessageStore:
+    """``<root>/<contract_id>/<work_record_id>.jsonl``, one envelope per line."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = root.resolve(strict=False)
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def append(
+        self,
+        *,
+        contract_id: str,
+        work_record_id: str,
+        sender_agent_id: str,
+        channel_id: str,
+        kind: MessageKind,
+        body: str,
+        references: list[MessageReference],
+        now: datetime | None = None,
+        recipient_agent_id: str | None = None,
+        recipient_role: str | None = None,
+        verdict: Literal["block", "clear"] | None = None,
+        head_sha: str | None = None,
+    ) -> MessageEnvelope:
+        """Store one envelope. Raises ``PermissionError`` on a sealed Contract.
+
+        A `result` that names no addressee answers the `message` it references, so its
+        recipient is that Message's sender (PRD issue 53: `result` wakes the requester).
+        """
+
+        self._require_open(contract_id)
+        if kind is MessageKind.RESULT and not recipient_agent_id and not recipient_role:
+            recipient_agent_id = self._requester_of(contract_id, work_record_id, references)
+        envelope = MessageEnvelope(
+            message_id=uuid4(),
+            sender_agent_id=UUID(sender_agent_id),
+            channel_id=UUID(channel_id),
+            work_record_id=UUID(work_record_id),
+            kind=kind,
+            references=list(references),
+            size_bytes=len(body.encode("utf-8")),
+            sent_at=now or datetime.now(UTC),
+            recipient_agent_id=UUID(recipient_agent_id) if recipient_agent_id else None,
+            recipient_role=recipient_role or None,
+            verdict=verdict,
+            head_sha=head_sha or None,
+            body=body,
+        )
+        path = self._path(contract_id, work_record_id)
+        _ensure_dir(path.parent)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(envelope.model_dump_json() + "\n")
+        path.chmod(_FILE_MODE)
+        return envelope
+
+    def read(
+        self, *, contract_id: str, work_record_id: str, channel_id: str | None = None
+    ) -> list[MessageEnvelope]:
+        """The Conversation, or one Channel of it. Raises ``PermissionError`` when sealed."""
+
+        self._require_open(contract_id)
+        return self._read(contract_id, work_record_id, channel_id)
+
+    def depth(self, *, contract_id: str, work_record_id: str, channel_id: str) -> int:
+        return len(self._read(contract_id, work_record_id, channel_id))
+
+    def pending(
+        self,
+        *,
+        contract_id: str,
+        work_record_id: str,
+        channel_id: str,
+        agent_id: str,
+        roles: tuple[str, ...] = (),
+    ) -> list[MessageEnvelope]:
+        """What one member has not yet seen: every Message on the Channel after its
+        cursor that is addressed to it -- by id, by a role it holds, or to nobody in
+        particular (a `note` to the Swarm) -- and not its own (PRD issue 53)."""
+
+        self._require_open(contract_id)
+        cursor = self._cursors(contract_id, work_record_id).get(agent_id, "")
+        envelopes = self._read(contract_id, work_record_id, channel_id)
+        unseen = _after(envelopes, cursor)
+        me = UUID(agent_id)
+        return [
+            envelope
+            for envelope in unseen
+            if envelope.sender_agent_id != me
+            and (
+                envelope.recipient_agent_id == me
+                or (envelope.recipient_role is not None and envelope.recipient_role in roles)
+                or (envelope.recipient_agent_id is None and envelope.recipient_role is None)
+            )
+        ]
+
+    def mark_consumed(
+        self, *, contract_id: str, work_record_id: str, agent_id: str, through: MessageEnvelope
+    ) -> None:
+        """Advance one member's cursor: the Directive that folded ``through`` in ran."""
+
+        cursors = self._cursors(contract_id, work_record_id)
+        cursors[agent_id] = str(through.message_id)
+        path = self._cursor_path(contract_id, work_record_id)
+        _ensure_dir(path.parent)
+        path.write_text(json.dumps(cursors), encoding="utf-8")
+        path.chmod(_FILE_MODE)
+
+    def transcript(self, request: TranscriptRequest) -> TranscriptDelivery:
+        """The pull-through's answer: every body, or the Contract state that seals them."""
+
+        contract_id = str(request.contract_id)
+        sealed = self.sealed_state(contract_id)
+        if sealed is not None:
+            return TranscriptDelivery(
+                request_id=request.request_id,
+                work_record_id=request.work_record_id,
+                refused=sealed,
+            )
+        return TranscriptDelivery(
+            request_id=request.request_id,
+            work_record_id=request.work_record_id,
+            messages=self._read(contract_id, str(request.work_record_id), None),
+        )
+
+    # ------------------------------------------------------------- lifecycle
+
+    def seal(self, contract_id: str, *, contract_state: str) -> int:
+        """Seal every store of the Contract (map ticket 10): kept, unreadable, until retention.
+
+        Returns how many Work Record stores the seal covers. Idempotent, and a Contract
+        with no store gets no marker -- there is nothing to retain.
+        """
+
+        contract_dir = self._root / contract_id
+        stores = _stores(contract_dir)
+        if not stores:
+            return 0
+        marker = contract_dir / SEALED_MARKER
+        marker.write_text(json.dumps({"contract_state": contract_state}), encoding="utf-8")
+        marker.chmod(_FILE_MODE)
+        return len(stores)
+
+    def sealed_state(self, contract_id: str) -> str | None:
+        marker = self._root / contract_id / SEALED_MARKER
+        if not marker.is_file():
+            return None
+        try:
+            loaded = json.loads(marker.read_text(encoding="utf-8"))
+        except ValueError:
+            return "terminated"
+        state = loaded.get("contract_state") if isinstance(loaded, Mapping) else None
+        return str(state) if state else "terminated"
+
+    def held(self) -> list[tuple[str, str]]:
+        """Every ``(contract_id, work_record_id)`` with a store on this Runner."""
+
+        if not self._root.is_dir():
+            return []
+        return [
+            (contract_dir.name, store.stem)
+            for contract_dir in sorted(self._root.iterdir())
+            if contract_dir.is_dir()
+            for store in _stores(contract_dir)
+        ]
+
+    def remove(self, contract_id: str, work_record_id: str) -> bool:
+        """The retention drop. A Contract whose last store went takes its seal with it."""
+
+        path = self._path(contract_id, work_record_id)
+        if not path.is_file():
+            return False
+        path.unlink()
+        self._cursor_path(contract_id, work_record_id).unlink(missing_ok=True)
+        contract_dir = path.parent
+        if not _stores(contract_dir):
+            shutil.rmtree(contract_dir, ignore_errors=True)
+        return True
+
+    # ------------------------------------------------------------- internals
+
+    def _require_open(self, contract_id: str) -> None:
+        sealed = self.sealed_state(contract_id)
+        if sealed is not None:
+            raise PermissionError(
+                f"the Message store of Contract {contract_id} is sealed ({sealed})"
+            )
+
+    def _path(self, contract_id: str, work_record_id: str) -> Path:
+        # Both segments are platform ids (UUIDs) by the time they reach here; refusing
+        # anything else keeps a path from escaping the root.
+        return self._root / str(UUID(contract_id)) / f"{UUID(work_record_id)}.jsonl"
+
+    def _cursor_path(self, contract_id: str, work_record_id: str) -> Path:
+        return self._path(contract_id, work_record_id).with_suffix(".cursors.json")
+
+    def _cursors(self, contract_id: str, work_record_id: str) -> dict[str, str]:
+        path = self._cursor_path(contract_id, work_record_id)
+        if not path.is_file():
+            return {}
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+        return {str(k): str(v) for k, v in loaded.items()} if isinstance(loaded, Mapping) else {}
+
+    def _requester_of(
+        self, contract_id: str, work_record_id: str, references: list[MessageReference]
+    ) -> str | None:
+        answered = {ref.value for ref in references if ref.kind is ReferenceKind.MESSAGE}
+        if not answered:
+            return None
+        return next(
+            (
+                str(envelope.sender_agent_id)
+                for envelope in self._read(contract_id, work_record_id, None)
+                if str(envelope.message_id) in answered
+            ),
+            None,
+        )
+
+    def _read(
+        self, contract_id: str, work_record_id: str, channel_id: str | None
+    ) -> list[MessageEnvelope]:
+        path = self._path(contract_id, work_record_id)
+        if not path.is_file():
+            return []
+        envelopes = [
+            MessageEnvelope.model_validate_json(line)
+            for line in path.read_text(encoding="utf-8").splitlines()
+            if line.strip()
+        ]
+        if channel_id is None:
+            return envelopes
+        wanted = UUID(channel_id)
+        return [envelope for envelope in envelopes if envelope.channel_id == wanted]
+
+
+def _stores(contract_dir: Path) -> list[Path]:
+    if not contract_dir.is_dir():
+        return []
+    return sorted(entry for entry in contract_dir.iterdir() if entry.suffix == ".jsonl")
+
+
+def _after(envelopes: list[MessageEnvelope], cursor: str) -> list[MessageEnvelope]:
+    if not cursor:
+        return envelopes
+    for index, envelope in enumerate(envelopes):
+        if str(envelope.message_id) == cursor:
+            return envelopes[index + 1 :]
+    return envelopes
+
+
+def _ensure_dir(contract_dir: Path) -> None:
+    """Root and Contract directory alike: the Runner's own, closed to every other uid."""
+
+    for directory in (contract_dir.parent, contract_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+        os.chmod(directory, _DIR_MODE)