meridian-eval 0.2.0__py3-none-any.whl

meridian/__init__.py

@@ -0,0 +1,15 @@
+"""Meridian — an agent evaluation harness.
+
+Four rules govern everything in this package:
+
+1. Every trial starts from a clean, isolated environment.
+2. Grade outcomes, not trajectories.
+3. Report pass^k, not a mean score.
+4. Every run is reproducible from its manifest.
+"""
+
+from __future__ import annotations
+
+from meridian.version import __version__
+
+__all__ = ["__version__"]

meridian/_assets/agents/terminal_agent/agent.py

@@ -0,0 +1,209 @@
+"""A general terminal agent: a LangGraph loop over one `bash` tool.
+
+    plan → act ⇄ tools → finish
+
+Unlike the checkout fixture, nothing here knows the task. It reads the prompt,
+works in the container's working directory through a shell, and stops when the
+model stops calling tools. That makes it the system under test for imported
+benchmark tasks (see `meridian import-harbor`).
+
+It calls the model through the Meridian proxy, never a provider, with no credential
+of its own.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Annotated, Any, TypedDict
+
+import httpx
+from langgraph.graph import END, StateGraph
+
+from terminal_agent.tools import TOOL_SCHEMAS, format_result, run_bash
+from terminal_agent.transcript import record
+
+# The proxy substitutes the model the operator chose, so this name is only a label.
+MODEL = os.environ.get("MERIDIAN_FIXTURE_MODEL", "meridian-model")
+MAX_TURNS = 30
+REQUEST_TIMEOUT_SECONDS = 180.0
+# The trial token budget is a ceiling on the whole trial, not on one reply.
+MAX_TOKENS_PER_REPLY = 4096
+
+PROMPTS = Path(__file__).resolve().parent / "prompts"
+
+
+def _append(existing: list[Any], incoming: list[Any]) -> list[Any]:
+    return [*existing, *incoming]
+
+
+class AgentState(TypedDict, total=False):
+    context: dict[str, Any]
+    messages: Annotated[list[dict[str, Any]], _append]
+    system: str
+    turns: int
+    tool_calls: Annotated[list[dict[str, Any]], _append]
+    input_tokens: int
+    output_tokens: int
+    error: str | None
+    completed: bool
+
+
+def plan(state: AgentState) -> AgentState:
+    context = state["context"]
+    return {
+        "system": (PROMPTS / "system.md").read_text(encoding="utf-8"),
+        "messages": [{"role": "user", "content": context["prompt"]}],
+        "turns": 0,
+        "input_tokens": 0,
+        "output_tokens": 0,
+        "tool_calls": [],
+        "completed": False,
+        "error": None,
+    }
+
+
+def act(state: AgentState) -> AgentState:
+    """One model turn, through the proxy."""
+    context = state["context"]
+    body = {
+        "model": MODEL,
+        "max_tokens": min(
+            int(context.get("max_tokens", MAX_TOKENS_PER_REPLY)), MAX_TOKENS_PER_REPLY
+        ),
+        "system": state.get("system", ""),
+        "messages": state.get("messages", []),
+        "tools": TOOL_SCHEMAS,
+    }
+    headers = {
+        "x-meridian-task": str(context.get("task_slug", "")),
+        "x-meridian-trial": str(context.get("trial_index", 0)),
+        "content-type": "application/json",
+    }
+    url = f"{context['model_base_url']}/v1/messages"
+    workdir = str(context.get("workdir", "."))
+    asked = time.monotonic()
+    record(workdir, "model_request", turn=state.get("turns", 0) + 1)
+    try:
+        response = httpx.post(url, json=body, headers=headers, timeout=REQUEST_TIMEOUT_SECONDS)
+    except httpx.HTTPError as exc:
+        record(workdir, "model_error", error=f"{type(exc).__name__}: {exc}")
+        return {"error": f"model call failed: {exc}", "completed": False}
+    if response.status_code != 200:
+        record(workdir, "model_error", status=response.status_code, body=response.text)
+        return {
+            "error": f"model returned {response.status_code}: {response.text[:400]}",
+            "completed": False,
+        }
+
+    payload = response.json()
+    usage = payload.get("usage") or {}
+    reply = payload.get("content") or []
+    record(
+        workdir,
+        "model_reply",
+        seconds=round(time.monotonic() - asked, 1),
+        stop=payload.get("stop_reason"),
+        text=" ".join(
+            b.get("text", "") for b in reply if isinstance(b, dict) and b.get("type") == "text"
+        ),
+        commands=[
+            (b.get("input") or {}).get("command")
+            for b in reply
+            if isinstance(b, dict) and b.get("type") == "tool_use"
+        ],
+    )
+    return {
+        "messages": [{"role": "assistant", "content": payload.get("content") or []}],
+        "turns": state.get("turns", 0) + 1,
+        "input_tokens": state.get("input_tokens", 0) + int(usage.get("input_tokens", 0)),
+        "output_tokens": state.get("output_tokens", 0) + int(usage.get("output_tokens", 0)),
+        "completed": payload.get("stop_reason") != "tool_use",
+    }
+
+
+def tools(state: AgentState) -> AgentState:
+    """Run every tool call the model made, in order."""
+    workdir = str(state["context"]["workdir"])
+    results: list[dict[str, Any]] = []
+    recorded: list[dict[str, Any]] = []
+    for block in state["messages"][-1].get("content", []):
+        if not isinstance(block, dict) or block.get("type") != "tool_use":
+            continue
+        arguments = dict(block.get("input") or {})
+        if block.get("name") != "bash" or not isinstance(arguments.get("command"), str):
+            text, ok = f"[unknown tool or bad arguments: {json.dumps(arguments)[:200]}]", False
+        else:
+            began = time.monotonic()
+            result = run_bash(
+                arguments["command"],
+                workdir=workdir,
+                timeout_seconds=arguments.get("timeout_seconds"),
+            )
+            text, ok = format_result(result), result["error"] is None
+            record(
+                workdir,
+                "command",
+                command=arguments["command"],
+                exit_code=result["exit_code"],
+                error=result["error"],
+                seconds=round(time.monotonic() - began, 1),
+                output=result["output"],
+            )
+        recorded.append({"name": str(block.get("name")), "ok": ok})
+        results.append(
+            {
+                "type": "tool_result",
+                "tool_use_id": block.get("id"),
+                "content": text,
+                "is_error": not ok,
+            }
+        )
+    return {"messages": [{"role": "user", "content": results}], "tool_calls": recorded}
+
+
+def route(state: AgentState) -> str:
+    if state.get("error") or state.get("completed"):
+        return "finish"
+    if state.get("turns", 0) >= MAX_TURNS:
+        return "out_of_turns"
+    last = state["messages"][-1]
+    wants_tools = any(
+        isinstance(block, dict) and block.get("type") == "tool_use"
+        for block in last.get("content", [])
+    )
+    return "tools" if wants_tools else "finish"
+
+
+def out_of_turns(state: AgentState) -> AgentState:
+    # An agent failure, not a harness one: it had its turns and did not finish.
+    return {"error": f"gave up after {MAX_TURNS} turns", "completed": False}
+
+
+def finish(state: AgentState) -> AgentState:
+    return {"completed": state.get("error") is None}
+
+
+def build_graph() -> Any:
+    builder: StateGraph[AgentState] = StateGraph(AgentState)
+    builder.add_node("plan", plan)
+    builder.add_node("act", act)
+    builder.add_node("tools", tools)
+    builder.add_node("out_of_turns", out_of_turns)
+    builder.add_node("finish", finish)
+    builder.set_entry_point("plan")
+    builder.add_edge("plan", "act")
+    builder.add_conditional_edges(
+        "act",
+        route,
+        {"tools": "tools", "finish": "finish", "out_of_turns": "out_of_turns"},
+    )
+    builder.add_edge("tools", "act")
+    builder.add_edge("out_of_turns", "finish")
+    builder.add_edge("finish", END)
+    return builder.compile()
+
+
+graph = build_graph()

meridian/_assets/agents/terminal_agent/prompts/system.md

@@ -0,0 +1,11 @@
+You are an autonomous software engineer working in a Linux container. You have one tool, `bash`, which runs a shell command in your working directory and returns its output and exit code.
+
+Work toward the task you are given:
+
+- Look before you change things: list files and read what is relevant.
+- Make the change, then check your own work by running it. Do not assume it worked.
+- Commands have a time limit and large outputs are truncated, so prefer targeted commands.
+- You have no internet access and no root privileges. Use only what is installed.
+- When the task is complete, stop calling tools and reply with a one-line summary.
+
+Your result is judged only by the final state of the container, so make sure the files and outputs the task asks for exist and are correct before you stop.

meridian/_assets/agents/terminal_agent/tools.py

@@ -0,0 +1,97 @@
+"""The terminal agent's one tool: run a shell command.
+
+Standard library only, so it can be tested on the host without LangGraph.
+
+The command runs inside the trial container, which is already the sandbox: a
+read-only root filesystem, an unprivileged user, no capabilities and no network.
+This module adds only what any shell tool needs -- a time limit and bounded output.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from typing import Any
+
+MAX_OUTPUT_CHARS = 8000
+DEFAULT_TIMEOUT_SECONDS = 60
+MAX_TIMEOUT_SECONDS = 300
+
+TOOL_SCHEMAS: list[dict[str, Any]] = [
+    {
+        "name": "bash",
+        "description": (
+            "Run a shell command in the working directory. Returns the combined "
+            "stdout/stderr and the exit code. Commands that run longer than the "
+            "timeout are killed."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "The command to run."},
+                "timeout_seconds": {
+                    "type": "integer",
+                    "description": f"Time limit, at most {MAX_TIMEOUT_SECONDS} (default "
+                    f"{DEFAULT_TIMEOUT_SECONDS}).",
+                },
+            },
+            "required": ["command"],
+        },
+    }
+]
+
+
+def truncate(text: str, limit: int = MAX_OUTPUT_CHARS) -> str:
+    """Keep the start and the end of long output; the middle is rarely the point."""
+    if len(text) <= limit:
+        return text
+    head = limit // 2
+    tail = limit - head
+    omitted = len(text) - limit
+    return f"{text[:head]}\n... [{omitted} characters omitted] ...\n{text[-tail:]}"
+
+
+def run_bash(command: str, *, workdir: str, timeout_seconds: int | None = None) -> dict[str, Any]:
+    """Run `command` with bash in `workdir`. Never raises; failures are results."""
+    timeout = DEFAULT_TIMEOUT_SECONDS if timeout_seconds is None else timeout_seconds
+    timeout = max(1, min(int(timeout), MAX_TIMEOUT_SECONDS))
+    env = {
+        "PATH": os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
+        "HOME": "/tmp",
+        "LANG": "C.UTF-8",
+        "TERM": "dumb",
+    }
+    try:
+        completed = subprocess.run(
+            ["bash", "-c", command],
+            cwd=workdir,
+            env=env,
+            capture_output=True,
+            timeout=timeout,
+            stdin=subprocess.DEVNULL,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        partial = (exc.stdout or b"") + (exc.stderr or b"")
+        output = partial.decode("utf-8", errors="replace")
+        return {
+            "exit_code": None,
+            "output": truncate(output),
+            "error": f"timed out after {timeout}s",
+        }
+    except OSError as exc:
+        return {"exit_code": None, "output": "", "error": f"{type(exc).__name__}: {exc}"}
+    output = (completed.stdout + completed.stderr).decode("utf-8", errors="replace")
+    return {"exit_code": completed.returncode, "output": truncate(output), "error": None}
+
+
+def format_result(result: dict[str, Any]) -> str:
+    """The text the model sees for one command."""
+    lines = []
+    if result["error"]:
+        lines.append(f"[{result['error']}]")
+    elif result["exit_code"] != 0:
+        lines.append(f"[exit code {result['exit_code']}]")
+    if result["output"]:
+        lines.append(result["output"])
+    return "\n".join(lines) if lines else "[no output]"

meridian/_assets/agents/terminal_agent/transcript.py

@@ -0,0 +1,38 @@
+"""An append-only transcript of what the agent did, written as it goes.
+
+Written line by line and flushed immediately, so that when the harness kills the
+agent at its deadline the record of what it was doing survives. The harness reads
+the tail of this file into a timeout verdict.
+
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+TRANSCRIPT_RELATIVE = ".meridian/transcript.jsonl"
+FIELD_LIMIT = 400
+
+
+def _clip(value: Any) -> Any:
+    if isinstance(value, str) and len(value) > FIELD_LIMIT:
+        return value[:FIELD_LIMIT] + f"... [{len(value) - FIELD_LIMIT} more]"
+    return value
+
+
+def record(workdir: str, event: str, **fields: Any) -> None:
+    """Append one event. Never raises: a transcript must not be able to fail a trial."""
+    line = {"t": round(time.time(), 2), "event": event}
+    line.update({key: _clip(value) for key, value in fields.items()})
+    try:
+        path = Path(workdir) / TRANSCRIPT_RELATIVE
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(line, sort_keys=True) + "\n")
+            handle.flush()
+    except OSError:
+        pass

meridian/_assets/proxy.Dockerfile

@@ -0,0 +1,43 @@
+# The model proxy image.
+#
+# Built with the repository root as context because it ships a slice of the
+# harness. Deliberately minimal: this container holds the only provider
+# credential in the system, so the less it contains the better.
+FROM python:3.13-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN pip install --no-cache-dir \
+        "starlette==0.45.3" \
+        "uvicorn==0.34.0" \
+        "httpx==0.28.1" \
+        "pydantic==2.10.6" \
+        "pyyaml==6.0.2"
+
+COPY src/meridian/__init__.py            /opt/meridian/meridian/__init__.py
+COPY src/meridian/version.py             /opt/meridian/meridian/version.py
+COPY src/meridian/hashing.py             /opt/meridian/meridian/hashing.py
+COPY src/meridian/config.py              /opt/meridian/meridian/config.py
+# cassette.py validates tape names against the task schema's slug alphabet, so
+# the proxy needs that one model module (pydantic only, no further imports).
+COPY src/meridian/models/__init__.py     /opt/meridian/meridian/models/__init__.py
+COPY src/meridian/models/task.py         /opt/meridian/meridian/models/task.py
+COPY src/meridian/runtime/__init__.py    /opt/meridian/meridian/runtime/__init__.py
+COPY src/meridian/runtime/secrets.py     /opt/meridian/meridian/runtime/secrets.py
+COPY src/meridian/runtime/proxy/         /opt/meridian/meridian/runtime/proxy/
+
+ENV PYTHONPATH=/opt/meridian \
+    MERIDIAN_CASSETTE_DIR=/cassettes \
+    MERIDIAN_PROXY_PORT=8080
+
+# Named `meridian`, not `proxy`: Debian base images already ship a `proxy` user
+# and groupadd exits 9 on the collision.
+RUN groupadd --gid 10002 meridian && useradd --uid 10002 --gid 10002 --no-create-home meridian \
+    && mkdir -p /cassettes && chown 10002:10002 /cassettes
+USER 10002:10002
+
+EXPOSE 8080
+ENTRYPOINT ["python3", "-m", "meridian.runtime.proxy.server"]

meridian/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Adapters run **inside** the trial container, never in the harness process.
+
+The harness never imports the system under test — it ships this package into the
+container and lets the entrypoint resolve the adapter spec there. That is what
+makes "framework-agnostic" a structural property rather than a claim: the harness
+has no way to depend on a framework it cannot import.
+"""

meridian/adapters/base.py

@@ -0,0 +1,60 @@
+"""Adapter spec strings: `kind:module:attribute`.
+
+`langgraph:checkout_agent.agent:graph` says *which adapter* to use, *which
+module* holds the system under test, and *which attribute* of it to invoke. The
+harness only ever parses this; it resolves it inside the container.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+from typing import Any
+
+KNOWN_KINDS = ("langgraph", "subprocess")
+
+
+class AdapterSpecError(ValueError):
+    """A malformed or unknown adapter spec. A configuration error, not a verdict."""
+
+
+@dataclass(frozen=True)
+class AdapterSpec:
+    """A parsed `kind:module:attribute` triple."""
+
+    kind: str
+    module: str
+    attribute: str
+
+    @classmethod
+    def parse(cls, raw: str) -> AdapterSpec:
+        parts = raw.split(":")
+        if len(parts) != 3 or not all(part.strip() for part in parts):
+            raise AdapterSpecError(
+                f"adapter spec {raw!r} must be 'kind:module:attribute', "
+                f"e.g. 'langgraph:checkout_agent.agent:graph'"
+            )
+        kind, module, attribute = (part.strip() for part in parts)
+        if kind not in KNOWN_KINDS:
+            raise AdapterSpecError(
+                f"unknown adapter kind {kind!r}; Meridian ships {', '.join(KNOWN_KINDS)}"
+            )
+        return cls(kind=kind, module=module, attribute=attribute)
+
+    def __str__(self) -> str:
+        return f"{self.kind}:{self.module}:{self.attribute}"
+
+    def resolve_target(self) -> Any:
+        """Import the module and return the attribute. Container-side only."""
+        try:
+            module = importlib.import_module(self.module)
+        except ImportError as exc:
+            raise AdapterSpecError(
+                f"cannot import {self.module!r} for adapter spec {self}: {exc}"
+            ) from exc
+        try:
+            return getattr(module, self.attribute)
+        except AttributeError as exc:
+            raise AdapterSpecError(
+                f"module {self.module!r} has no attribute {self.attribute!r}"
+            ) from exc

meridian/adapters/entrypoint.py

@@ -0,0 +1,174 @@
+"""The in-container entrypoint. PID 1's child; the harness never runs this.
+
+Reads a serialized `TrialContext`, resolves the adapter spec, runs the agent,
+and writes `result.json` and `transcript.json` next to the payload. It exits 0
+whenever it *ran the agent to a conclusion* — including a conclusion the agent
+did not like — because the trial's verdict is decided outside, by grading the
+final state. A non-zero exit here means the entrypoint itself could not run,
+which is a harness error.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import traceback
+from pathlib import Path
+from typing import Any
+
+from meridian.adapters.base import AdapterSpec, AdapterSpecError
+from meridian.models.adapter import AdapterResult, TrialContext
+
+EXIT_OK = 0
+EXIT_ENTRYPOINT_FAILED = 70
+
+# Written when the entrypoint itself could not run. The harness reads it so the
+# trial's detail says *what* was misconfigured rather than only that something
+# was.
+HARNESS_ERROR_FILE = "harness_error.txt"
+
+# Short: this only ever runs after the agent has already failed, and the answer
+# is "is anything listening", not "is it fast".
+PROXY_HEALTH_TIMEOUT_SECONDS = 5.0
+
+
+def build_adapter(spec: AdapterSpec) -> Any:
+    """Pick the adapter implementation for a spec kind.
+
+    Imported lazily and per-kind: the LangGraph adapter imports LangGraph, and a
+    subprocess trial should not pay for — or fail on — a framework it never uses.
+    """
+    if spec.kind == "subprocess":
+        from meridian.adapters.subprocess_adapter import SubprocessAdapter
+
+        return SubprocessAdapter(spec)
+    if spec.kind == "langgraph":
+        from meridian.adapters.langgraph_adapter import LangGraphAdapter
+
+        return LangGraphAdapter(spec)
+    raise ValueError(f"no adapter implementation for kind {spec.kind!r}")
+
+
+def record_harness_error(payload_dir: Path, message: str) -> int:
+    """Report a Meridian misconfiguration, not an agent failure."""
+    (payload_dir / HARNESS_ERROR_FILE).write_text(message, encoding="utf-8")
+    (payload_dir / "traceback.txt").write_text(traceback.format_exc(), encoding="utf-8")
+    return EXIT_ENTRYPOINT_FAILED
+
+
+def proxy_is_unreachable(base_url: str) -> bool:
+    """Ask the proxy whether it is alive. Used only to explain a failure.
+
+    This is the seam that separates "the agent failed" from "the agent was never
+    given a model". It asks the proxy directly rather than matching on the text of
+    the agent's error, because the wording of that error belongs to whatever
+    framework raised it and will not survive an upgrade — and a classification
+    rule built on someone else's error string fails silently and in the expensive
+    direction.
+
+    Unreachable means *refused or unanswered*, not "returned an error". A proxy
+    that answers with a budget refusal or a cassette miss is working exactly as
+    designed, and those are genuine agent-visible failures.
+    """
+    if not base_url:
+        return False
+    try:
+        import httpx
+    except ImportError:
+        # The trial image supplies httpx, not the payload. An environment without
+        # it must not turn every agent failure into an unanswerable question:
+        # raising here would escape `run()`, exit EXIT_ENTRYPOINT_FAILED, and be
+        # classified as a harness error — which is *retried*. Every genuine agent
+        # `fail` on such an image would then get a second attempt, which is the
+        # one thing the retry policy exists to forbid.
+        return False
+
+    try:
+        response = httpx.get(
+            f"{base_url.rstrip('/')}/healthz", timeout=PROXY_HEALTH_TIMEOUT_SECONDS
+        )
+    except Exception:
+        # Deliberately broad. `httpx.InvalidURL` is not an `HTTPError`, so a
+        # malformed base URL would otherwise crash the entrypoint rather than
+        # answer the question. Anything that prevents an answer means the proxy
+        # could not be confirmed alive, which is what the caller asked.
+        return True
+    return response.status_code >= 500
+
+
+async def run(context_path: Path) -> int:
+    payload_dir = context_path.parent
+    raw = json.loads(context_path.read_text(encoding="utf-8"))
+
+    # Everything up to and including resolving the adapter is configuration. A
+    # failure here says the harness was set up wrong, and calling it an agent
+    # failure would put a configuration mistake into the score.
+    try:
+        adapter_spec = AdapterSpec.parse(raw.pop("adapter_spec"))
+        ctx = TrialContext.model_validate(raw)
+        adapter = build_adapter(adapter_spec)
+        adapter_spec.resolve_target()
+    except (AdapterSpecError, ValueError) as exc:
+        return record_harness_error(payload_dir, f"{type(exc).__name__}: {exc}")
+
+    try:
+        result = await adapter.invoke(ctx)
+    except AdapterSpecError as exc:
+        return record_harness_error(payload_dir, f"{type(exc).__name__}: {exc}")
+    except Exception as exc:  # the agent blew up: an agent failure, not a harness one
+        result = AdapterResult(
+            completed=False,
+            error=f"{type(exc).__name__}: {exc}",
+            transcript_path=str(payload_dir / "transcript.json"),
+        )
+        (payload_dir / "traceback.txt").write_text(traceback.format_exc(), encoding="utf-8")
+    finally:
+        await adapter.teardown()
+
+    # An agent that could not reach the model has not been evaluated, so its
+    # failure is Meridian's and not the agent's. Checked here rather than at the
+    # exception site because an agent may *return* the failure instead of raising
+    # it -- the checkout fixture catches httpx errors and reports them as an
+    # AdapterResult -- and both paths must classify the same way.
+    #
+    # Getting this wrong is expensive in the direction that wastes a person's
+    # afternoon: a dead proxy fails every trial of every task, the gate reports
+    # the largest regression it has ever seen, and the developer reverts a change
+    # that was never the cause.
+    if result.error and proxy_is_unreachable(ctx.model_base_url):
+        return record_harness_error(
+            payload_dir,
+            f"the model proxy at {ctx.model_base_url} did not answer its health "
+            f"check, so the agent was never given a model. The agent reported: "
+            f"{result.error}",
+        )
+
+    (payload_dir / "result.json").write_text(
+        result.model_dump_json(indent=2),
+        encoding="utf-8",
+    )
+    transcript = payload_dir / "transcript.json"
+    if not transcript.exists():
+        transcript.write_text(
+            json.dumps({"task": ctx.task_slug, "trial": ctx.trial_index, "turns": result.turns}),
+            encoding="utf-8",
+        )
+    return EXIT_OK
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print("usage: entrypoint.py <context.json>", file=sys.stderr)
+        return EXIT_ENTRYPOINT_FAILED
+    try:
+        return asyncio.run(run(Path(argv[1])))
+    except Exception:
+        # The entrypoint itself failed. This is Meridian's problem, and the
+        # non-zero exit is what tells the runner to classify it as one.
+        traceback.print_exc()
+        return EXIT_ENTRYPOINT_FAILED
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised inside the container
+    raise SystemExit(main(sys.argv))