Files
HermenixandClaude Opus 5 56493721f0 test(mcp): the resource routing, the toolsets, and the guest check for both
46 more unit tests, and `vm-mcp` rewritten around the new split (21 subtests,
up from 14).

`test_mcp_resources.py` is the new file and its subject is what the resource
layer actually decides: which entry a URI resolves to, which query parameters
it will accept, and the argv each read builds. The cases that matter are the
ones a reshuffle would quietly break -- a literal route beating a template
(`hhstream://sessions` is the listing, not a session with a blank id), a
switch parameter becoming a bare flag or nothing at all (`--all=false` is not
something the CLI takes), an undeclared parameter being refused rather than
dropped, a frame's media type being sniffed rather than assumed, and a refusal
being *raised* instead of returned as the body.

One test exists only to stop a future kindness: there must be no resource for
the reconciling container read, because that one writes.

`test_mcp_server.py` grows the protocol-level half -- both listings, a read
that returns JSON, a read that returns a blob, a refused read arriving as
`McpError`, and a toolset selection that narrows the tools while leaving the
resources alone. The tool and toolset tests move with the surface: the
read-only verbs are asserted *absent* by name rather than merely missing, so
re-adding one is a failure instead of a silent widening of what mcp-v2
narrowed.

In the guest, the subtest the whole surface turns on is now measured rather
than described: two reads of `hhstream://sessions/<id>` must NOT move the idle
deadline, and `session_touch` must. It also asks for the same container two
ways and checks the answers agree, reads one output's frame as a blob and
confirms the `shot` tool reports the same geometry, and proves `--toolsets`
makes an omitted tool unreachable and not merely unlisted.

`checks/lib/mcp_client.py` gains `--resources`, `--read` and `--server-arg`,
and exits 3 rather than 2 on a protocol error -- so "the server refused this
read" stays distinguishable from "the server did not answer at all", which is
the distinction that keeps the refusal subtests from passing for the wrong
reason.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
2026-10-11 11:50:12 +00:00

390 lines
14 KiB
Python

"""The runner: how the CLI is called in process, decoded, and mapped to a code.
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
the subject is what this layer decides -- the argv list and the mapping. Three
tests drive the **real** entry point, against a control socket that does not
exist: that is the honest way to prove the dispatch, the capture and the
exit-code mapping against the CLI's actual parser without standing a daemon up.
"""
from __future__ import annotations
import contextlib
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, media
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
# ── the call ───────────────────────────────────────────────────────────────
def test_the_argv_reaches_the_entry_point_unchanged():
fake = mcp_fake.FakeCli(stdout="hello\n")
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.ok
assert outcome.stdout == "hello\n"
assert fake.argv == ["session", "list", "--json"]
assert outcome.argv == ["session", "list", "--json"]
def test_a_metacharacter_is_one_argument_and_never_a_statement():
"""There is no shell between a tool and the CLI, and no string either."""
fake = mcp_fake.FakeCli()
nasty = "; rm -rf / #"
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
"""A print on stdout here would be a parse error at the client."""
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
outcome = invoke.Runner(fake).run(["status"])
assert outcome.stdout == "on stdout\n"
assert outcome.stderr == "on stderr\n"
escaped = capsys.readouterr()
assert escaped.out == ""
assert escaped.err == ""
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
fake = mcp_fake.FakeCli(raises=SystemExit(2))
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
# `sys.exit("message")` is status 1 in a real process, and the message is
# the exit code object rather than something printed.
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
fake = mcp_fake.FakeCli(raises=SystemExit(None))
assert invoke.Runner(fake).run(["status"]).returncode == 0
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
"""What a CLI process would have done, rather than a transport error."""
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.returncode == invoke.GENERIC_FAILURE
assert "RuntimeError: boom" in outcome.stderr
assert "Traceback" in outcome.stderr
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
"""BaseException is caught on purpose; the code still says "failed"."""
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
outcome = invoke.Runner(fake).run(["session", "list"])
assert outcome.returncode == invoke.GENERIC_FAILURE
def test_a_call_runs_with_the_serialising_lock_held():
"""The CLI prints to a process-global stdout, so one call at a time.
Asserted from inside the call rather than by racing two threads and hoping
their output interleaves: a race that passes by luck is not a test. The
private name is the point -- what is being asserted is that this specific
lock is held while a handler runs.
"""
def probing(argv):
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
if free:
invoke._ONE_AT_A_TIME.release()
print("free" if free else "held", end="")
return 0
assert invoke.Runner(probing).run(["status"]).stdout == "held"
# ── decoding ───────────────────────────────────────────────────────────────
def test_the_protocol_object_is_read_from_stdout_on_success():
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
def test_the_protocol_object_is_read_from_stderr_on_failure():
"""The CLI's own split: an error goes to stderr whatever the output mode."""
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
fake = mcp_fake.FakeCli(
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
)
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
assert not outcome.ok
assert outcome.payload() == fields
def test_an_object_printed_under_a_bare_line_is_still_found():
"""`session start` prints the id beside its object; parsing must survive it."""
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
"ok": True,
"id": "s-1",
}
def test_no_json_at_all_is_none_rather_than_an_invention():
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
assert invoke.Runner(fake).run(["status"]).payload() is None
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
assert invoke.first_json_object("[1, 2, 3]") is None
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
# ── the real entry point, with nothing listening ───────────────────────────
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.USAGE)
assert "invalid choice" in outcome.stderr
# And nothing escaped onto the real stdout: argparse prints usage there for
# --help and to stderr for an error, and both are captured.
assert outcome.stdout == ""
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
"""No socket, no daemon, no fake: the mapping end to end."""
outcome = invoke.Runner().run(["session", "list", "--json"])
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
payload = outcome.payload()
assert payload is not None
assert payload["error"] == "daemon_unreachable"
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
"""Exit 9 is produced by the CLI before the socket is touched at all."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.NO_LEASE)
assert (outcome.payload() or {}).get("error") == "no_lease"
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
"""The one capability lost by calling the CLI in process, said out loud."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "cannot read" in outcome.stderr
assert "sg hhstream" in outcome.stderr
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
readable = tmp_path / "stream.sock"
readable.write_bytes(b"")
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "sg hhstream" not in outcome.stderr
def test_a_session_verb_never_earns_the_frame_socket_hint():
"""It has nothing to do with the control socket, so it must not be offered."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
["session", "pointer", "acquire", "--json", "--", "s-1"]
)
assert "sg hhstream" not in outcome.stderr
# ── the exit-code table ────────────────────────────────────────────────────
@pytest.mark.parametrize(
"code",
[
ExitCode.USAGE,
ExitCode.NO_SUCH_SESSION,
ExitCode.BAD_STATE,
ExitCode.DAEMON_UNREACHABLE,
ExitCode.POLICY,
ExitCode.TIMEOUT,
ExitCode.BUSY,
ExitCode.NO_LEASE,
ExitCode.COMPOSITOR,
],
)
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
"""A new code in the frozen table must not fall through to a generic line."""
text = invoke.remedy_for(int(code))
assert text.startswith(f"exit {int(code)} ({code.name})")
assert int(code) in invoke.REMEDY
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
busy = invoke.remedy_for(int(ExitCode.BUSY))
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
assert "hhstream://pointer" in busy and "wait" in busy
assert "pointer_acquire" in none_held
# "acquire one" must not be the advice for BUSY: that is the one confusion
# the two codes exist to prevent.
assert "pointer_acquire" not in busy
def test_an_unclassified_code_is_still_a_failure_and_says_so():
text = invoke.remedy_for(42)
assert "exit 42 (UNCLASSIFIED)" in text
assert "do not assume anything happened" in text
def test_generic_failure_is_its_own_case():
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
# ── launch, for `run` ──────────────────────────────────────────────────────
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
"""`run` launches and forgets, and a killed server must not take it along."""
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
try:
assert not spawned.exited
assert spawned.pid > 0
os.kill(spawned.pid, 0)
# Its own session, so a client that kills this server's process group
# does not kill the desktop with it.
assert os.getsid(spawned.pid) == spawned.pid
assert os.getsid(spawned.pid) != os.getsid(0)
finally:
with contextlib.suppress(ProcessLookupError):
os.kill(spawned.pid, signal.SIGTERM)
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
spawned = invoke.Runner().launch(["false"], settle=5.0)
assert spawned.exited
assert spawned.pid > 0
def test_launch_hands_back_what_a_failing_application_said(wayland):
spawned = invoke.Runner().launch(
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
)
assert spawned.exited
assert "cannot open display" in spawned.stderr
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
assert spawned.exited
assert spawned.pid == 0
assert "no executable" in spawned.stderr
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
"""`env_for_session` exits with the message; it is handed on verbatim."""
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
(tmp_path / "empty").mkdir()
spawned = invoke.Runner().launch(["true"], settle=1.0)
assert spawned.exited
assert spawned.pid == 0
assert "no wayland socket" in spawned.stderr
assert "is the compositor up?" in spawned.stderr
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory with something `env_for_session` accepts in it.
A real AF_UNIX socket, because that function checks `is_socket()` -- an
empty file would make it refuse for a reason these tests are not about.
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
address is capped near 108 bytes and pytest's own paths are longer than
that.
"""
import socket
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(str(workdir / "wayland-0"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
yield workdir
listener.close()
# ── artefact readers ───────────────────────────────────────────────────────
def test_a_png_is_sniffed_by_its_header_not_its_extension():
image = media.sniff(mcp_fake.png(width=13, height=7))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
"""The publisher serves `image/jpeg` on the deployment machine."""
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
def test_an_unrecognised_format_is_none_rather_than_a_guess():
assert media.sniff(b"GIF89a\x00\x00") is None
assert media.sniff(b"") is None
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
assert found is not None
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
assert media.recording("/tmp/out.mp4\n") is None
assert media.recording("") is None
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
first = invoke.temp_name("recording", ".mp4")
assert "hhstream-mcp" in first
assert first.endswith(".mp4")
assert str(os.getpid()) in first