"""The tool table: the argv each tool builds, and what it makes of the answer. The subject is the shim and nothing else. Every test here drives a tool through :class:`hhstream_mcp.invoke.Runner` with a recording stand-in (:class:`mcp_fake.FakeCli`) where the CLI goes, and asserts on the argv it was handed -- which is the only thing this layer actually decides. Nothing in this file imports the MCP SDK: the table is standard library by design, so an argv bug is findable without a protocol stack. The SDK wiring is ``test_mcp_server.py``, and the real CLI entry point is exercised in ``test_mcp_invoke.py``. """ from __future__ import annotations import json import os import signal import mcp_fake import pytest from hhstreamd.protocol import ExitCode from hhstream_mcp import invoke, tools @pytest.fixture(autouse=True) def _isolated(monkeypatch, tmp_path): mcp_fake.isolate(monkeypatch, tmp_path) @pytest.fixture def call(): """`call("session_touch", {"id": "s-1"})` -> (Result, [argv, ...]).""" def _call(name, arguments, **script): fake = mcp_fake.FakeCli(**script) result = tools.BY_NAME[name].invoke(invoke.Runner(fake), arguments) return result, fake.calls return _call # ── the surface is all there ─────────────────────────────────────────────── #: Every tool `docs/CONTRACT-mcp.md` §3 freezes, which is every verb of the CLI. #: Written out rather than derived from the table, because a list derived from #: the thing it checks cannot notice a missing entry. EXPECTED = { # frames "status", "shot", "record", "run", # lifecycle "session_start", "session_list", "session_status", "session_touch", "session_kill", "session_gc", "session_adopt", "session_logs", "session_container", "session_reconcile", # pointer "pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll", "pointer_down", "pointer_up", "pointer_release", "pointer_state", # keyboard "keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up", } def test_every_cli_verb_has_a_tool_and_nothing_else_does(): assert set(tools.BY_NAME) == EXPECTED def test_the_table_is_ordered_and_has_no_duplicate_names(): names = [tool.name for tool in tools.TOOLS] assert len(names) == len(set(names)) assert isinstance(tools.TOOLS, tuple) def test_only_the_verbs_that_read_are_marked_read_only(): """`session_container` with an id reconciles, which is a write.""" read_only = {tool.name for tool in tools.TOOLS if tool.read_only} assert read_only == { "status", "shot", "session_list", "session_status", "session_logs", "pointer_state", } assert not tools.BY_NAME["session_container"].read_only # `record` writes a file, so it is not read-only either. assert not tools.BY_NAME["record"].read_only assert tools.BY_NAME["session_kill"].destructive assert [t.name for t in tools.TOOLS if t.destructive] == ["session_kill"] # ── the two rules an agent gets wrong ────────────────────────────────────── #: The verbs the CLI's own note names as NOT counting as activity. Taken from #: the rule, so a tool that stopped carrying the warning is a failure here. NON_ACTIVITY = { "session_list", "session_status", "session_logs", "session_gc", "session_container", "session_reconcile", } GESTURES = { "pointer_move", "pointer_click", "pointer_scroll", "pointer_down", "pointer_up", "pointer_release", "keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up", } def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it(): for name in NON_ACTIVITY | GESTURES | {"session_start", "session_touch", "pointer_acquire"}: description = tools.BY_NAME[name].description assert tools.ACTIVITY_NOTE in description, f"{name} does not carry the activity rule" def test_the_idle_clock_rule_names_touch_as_the_only_mark_of_activity(): assert "`session_touch` is the ONLY thing" in tools.ACTIVITY_NOTE for verb in ("session_list", "session_status", "session_logs", "session_gc"): assert verb in tools.ACTIVITY_NOTE assert "do NOT count" in tools.ACTIVITY_NOTE def test_the_cli_still_owns_the_rule_this_wording_restates(): """A tripwire, not a duplication. `tools.ACTIVITY_NOTE` and `tools.LEASE_NOTE` are the CLI's two epilogues said in terms of tools. If the CLI's constants are renamed or stop saying what they say, these notes have silently become this server's own opinion -- so the originals are asserted to still exist and still carry the rule. """ import hhstream_session assert "ONLY" in hhstream_session.ACTIVITY_NOTE assert "touch" in hhstream_session.ACTIVITY_NOTE assert "no 'keyboard acquire'" in hhstream_session.KEYBOARD_LEASE_NOTE def test_every_keyboard_tool_says_it_needs_the_pointer_lease(): for name in ("keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"): description = tools.BY_NAME[name].description assert tools.LEASE_NOTE in description, f"{name} does not carry the lease rule" assert "POINTER lease" in tools.LEASE_NOTE assert "exit 9" in tools.LEASE_NOTE assert "`pointer_acquire`" in tools.LEASE_NOTE assert "There is no keyboard lease" in tools.LEASE_NOTE assert "only while it holds" in tools.LEASE_NOTE def test_holding_a_non_modifier_is_warned_about_where_it_can_happen(): assert tools.HOLD_NOTE in tools.BY_NAME["keyboard_down"].description assert "FLOODS THE WINDOW" in tools.HOLD_NOTE assert "the APPLICATION does the repeating" in tools.HOLD_NOTE def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached(): for name in GESTURES: schema = tools.BY_NAME[name].schema assert "lease" in schema["required"], f"{name} does not require a lease" # ...and acquire is the one that hands it out, so it must not require one. assert "lease" not in tools.BY_NAME["pointer_acquire"].schema.get("required", []) def test_every_schema_refuses_an_argument_this_server_would_drop(): for tool in tools.TOOLS: assert tool.schema["additionalProperties"] is False, tool.name assert tool.schema["type"] == "object" # ── the argv each tool builds ────────────────────────────────────────────── def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call): _, calls = call("session_touch", {"id": "s-1"}) assert calls == [["session", "touch", "--json", "--", "s-1"]] def test_omitted_arguments_become_no_flag_at_all(call): """A flag left off is the broker's own default; this layer must not supply one.""" _, calls = call("session_list", {}) assert calls == [["session", "list", "--json"]] _, calls = call("session_list", {"all": True}) assert calls == [["session", "list", "--json", "--all"]] _, calls = call("session_list", {"all": False}) assert calls == [["session", "list", "--json"]] def test_start_passes_the_application_argv_after_one_separator(call): _, calls = call( "session_start", { "app": "chromium", "argv": ["--new-window", "https://example.invalid"], "idle_timeout": "5m", "wait_ready": "30s", "request_id": "req-7", }, ) assert calls == [ [ "session", "start", "--json", "--idle-timeout=5m", "--wait-ready=30s", "--request-id=req-7", "--", "chromium", "--new-window", "https://example.invalid", ] ] def test_an_application_argument_that_looks_like_a_flag_is_not_eaten(call): """The `--` is what makes `--new-window` the application's and not the CLI's.""" _, calls = call("session_start", {"app": "foot", "argv": ["--help"]}) assert calls[0] == ["session", "start", "--json", "--", "foot", "--help"] def test_an_ephemeral_home_is_a_switch_and_a_home_is_a_value(call): _, calls = call("session_start", {"app": "foot", "ephemeral_home": True}) assert "--ephemeral-home" in calls[0] _, calls = call("session_start", {"app": "foot", "home": "/tmp/h"}) assert "--home=/tmp/h" in calls[0] def test_a_coordinate_pair_is_sent_in_the_cli_s_own_x_comma_y_form(call): _, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [0.25, 0.75]}) assert calls == [["session", "pointer", "move", "--json", "--lease=L", "--to=0.25,0.75", "--", "s-1"]] def test_a_negative_delta_stays_one_token_so_argparse_cannot_read_it_as_a_flag(call): _, calls = call("pointer_move", {"id": "s-1", "lease": "L", "by": [-0.1, 0.5]}) assert calls[0][5] == "--by=-0.1,0.5" def test_a_coordinate_is_not_rounded_on_the_way_through(call): """A caller that computed a number deserves the broker's verdict on it.""" _, calls = call("pointer_move", {"id": "s-1", "lease": "L", "to": [1 / 3, 0.0]}) assert calls[0][5] == f"--to={1 / 3!r},0.0" def test_a_negative_scroll_amount_stays_one_token(call): _, calls = call("pointer_scroll", {"id": "s-1", "lease": "L", "amount": -3, "axis": "horizontal"}) assert calls[0] == [ "session", "pointer", "scroll", "--json", "--lease=L", "--axis=horizontal", "--amount=-3.0", "--", "s-1", ] def test_pointer_state_takes_no_session_because_there_is_one_cursor(call): _, calls = call("pointer_state", {}) assert calls == [["session", "pointer", "state", "--json"]] assert tools.BY_NAME["pointer_state"].schema["properties"] == {} def test_a_typed_string_is_one_positional_after_the_separator(call): text = "--not-a-flag\nsecond line\twith a tab" _, calls = call("keyboard_type", {"id": "s-1", "lease": "L", "text": text}) assert calls == [["session", "keyboard", "type", "--json", "--lease=L", "--", "s-1", text]] def test_a_keysym_name_is_passed_through_untouched(call): _, calls = call("keyboard_key", {"id": "s-1", "lease": "L", "name": "BackSpace"}) assert calls[0][-1] == "BackSpace" def test_adopt_sends_the_pid_as_a_flag_because_the_cli_requires_it(call): _, calls = call("session_adopt", {"pid": 4242, "app": "chromium"}) assert calls == [["session", "adopt", "--json", "--pid=4242", "--app=chromium"]] def test_container_with_no_id_lists_and_with_an_id_reconciles(call): _, calls = call("session_container", {}) assert calls == [["session", "container", "--json"]] _, calls = call("session_container", {"id": "s-1"}) assert calls == [["session", "container", "--json", "--", "s-1"]] def test_logs_has_no_follow_because_a_tool_call_must_return(call): assert "follow" not in tools.BY_NAME["session_logs"].schema["properties"] _, calls = call("session_logs", {"id": "s-1", "lines": 5}) assert calls == [["session", "logs", "--json", "--lines=5", "--", "s-1"]] def test_status_is_not_run_with_json_because_the_verb_has_none(call): _, calls = call("status", {}, stdout="services:\n") assert calls == [["status"]] # ── what each tool makes of the answer ───────────────────────────────────── def test_a_successful_session_verb_passes_the_protocol_object_through(call): reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]} result, _ = call("session_list", {}, stdout=json.dumps(reply, indent=2)) assert not result.is_error assert result.data == reply # The text is the CLI's own stdout: a shim that re-rendered it would be # inventing a second format for the same facts. assert json.loads(result.text) == reply def test_acquire_puts_the_lease_id_where_the_next_call_will_look(call): reply = {"ok": True, "id": "s-1", "lease_id": "lease-abc", "bookmark": {"output": "hh-s-1"}} result, _ = call("pointer_acquire", {"id": "s-1"}, stdout=json.dumps(reply, indent=2)) assert result.data == reply assert result.text.startswith("lease_id: lease-abc") assert "pointer_release" in result.text def test_start_puts_the_new_session_id_first_and_names_the_idle_clock(call): reply = {"ok": True, "id": "s-9", "state": "running"} result, _ = call("session_start", {"app": "foot"}, stdout=json.dumps(reply, indent=2)) assert result.text.startswith("session id: s-9") assert "session_touch" in result.text def test_a_refusal_is_an_error_and_never_a_success(call): reply = { "ok": False, "error": "no_lease", "reason": "no pointer lease for s-1 on this socket", "hint": "run 'pointer acquire s-1' first", } result, _ = call( "pointer_click", {"id": "s-1", "lease": "stale"}, stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE), ) assert result.is_error assert result.data["ok"] is False assert result.data["exit_code"] == int(ExitCode.NO_LEASE) # The remedy first, then the broker's own words: an agent needs to know what # to do before it needs to know what was said. assert result.text.startswith("exit 9 (NO_LEASE)") assert "pointer_acquire" in result.text assert "error: no_lease" in result.text assert "no pointer lease for s-1" in result.text def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call): reply = {"ok": False, "error": "pointer_busy", "reason": "held by s-other"} result, _ = call( "pointer_acquire", {"id": "s-1"}, stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.BUSY), ) assert result.is_error assert result.text.startswith("exit 8 (BUSY)") assert "pointer_state" in result.text assert "s-other" in result.text def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call): """Exit 2 with no JSON anywhere -- argparse wrote prose to stderr.""" result, _ = call( "pointer_click", {"id": "s-1", "lease": "L", "button": "left"}, stderr="usage: hhstream session pointer click ...\nerror: argument --button: invalid choice\n", exit_code=int(ExitCode.USAGE), ) assert result.is_error assert result.data["exit_code"] == int(ExitCode.USAGE) assert "invalid choice" in result.text def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call): result, _ = call( "session_list", {}, stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n", exit_code=int(ExitCode.DAEMON_UNREACHABLE), ) assert result.is_error assert "HHSTREAM_SOCKET" in result.text assert "Frame tools" in result.text # ── shot and record ──────────────────────────────────────────────────────── def test_shot_captures_to_a_file_and_returns_the_bytes_with_the_geometry(call): frame = mcp_fake.png(width=320, height=180) result, calls = call("shot", {}, write_png=frame, stdout="/tmp/ignored.png\n") assert len(calls) == 1 verb, out = calls[0][0], calls[0][1] assert verb == "shot" assert out.startswith("--out=") # The temporary directory is gone, so the file cannot be read twice: the # bytes are in the reply or they are nowhere. assert result.image == frame assert result.media_type == "image/png" assert "320x180 image/png" in result.text assert result.data["width"] == 320 def test_shot_of_one_output_names_it_in_the_argv_and_in_the_reply(call): result, calls = call("shot", {"output": "hh-s-1"}, write_png=mcp_fake.png()) assert "--output=hh-s-1" in calls[0] assert "output 'hh-s-1'" in result.text assert result.data["output"] == "hh-s-1" def test_shot_tells_the_truth_about_a_format_it_cannot_read(call): result, _ = call("shot", {}, write_png=b"GIF89a-not-an-image") assert not result.is_error assert result.image is None assert "does not recognise" in result.text def test_shot_does_not_claim_an_image_when_the_cli_wrote_no_file(call): """Exit 0 and no artefact is still a failure; the alternative is a lie.""" result, _ = call("shot", {}, stdout="/tmp/somewhere.png\n") assert result.is_error assert result.data["error"] == "no_artifact" def test_shot_passes_a_refusal_through_without_reading_a_file(call): result, _ = call( "shot", {"output": "hh-gone"}, stderr="hhstream: could not capture output 'hh-gone': unknown output\n", exit_code=1, ) assert result.is_error assert result.image is None assert "unknown output" in result.text def test_record_returns_the_path_and_the_measured_rate_not_the_video(call): destination = "/tmp/hhstream-mcp/clip.mp4" result, calls = call( "record", {"seconds": 3, "out": destination}, stdout=f"{destination} (28 frames in 3.01s -> 9 fps)\n", ) assert calls[0] == ["record", f"--out={destination}", "--seconds=3"] assert result.image is None assert result.data == { "ok": True, "path": destination, "frames": 28, "seconds": 3.01, "fps": 9, } assert "measured 9 fps" in result.text def test_record_without_a_destination_generates_one_and_names_it(call): result, calls = call("record", {}, stdout="/x (1 frames in 1.00s -> 1 fps)\n") flag = next(a for a in calls[0] if a.startswith("--out=")) assert "hhstream-mcp" in flag assert flag.endswith(".mp4") assert result.data["ok"] is True def test_record_of_one_output_passes_the_rate_target_through(call): _, calls = call( "record", {"seconds": 2, "output": "hh-s-1", "fps": 4, "keep": True, "work_dir": "/tmp/w"}, stdout="/x (8 frames in 2.00s -> 4 fps)\n", ) # The generated --out is asserted by the test above; what matters here is # the order and form of everything after it. assert calls[0][0] == "record" assert calls[0][2:] == [ "--seconds=2", "--output=hh-s-1", "--fps=4", "--work-dir=/tmp/w", "--keep", ] # ── run ──────────────────────────────────────────────────────────────────── def test_run_reports_the_application_s_pid_and_that_it_is_unmanaged(wayland): result = tools.BY_NAME["run"].invoke( invoke.Runner(), {"argv": ["sleep", "30"], "settle_s": 0.3} ) try: assert not result.is_error assert result.data["managed"] is False assert result.data["pid"] > 0 assert result.data["argv"] == ["sleep", "30"] # The tool's own words have to point at the managed alternative, or an # agent reaches for `run` because it is the shorter name. assert "session_start" in result.text assert "UNMANAGED" in result.text finally: import contextlib with contextlib.suppress(ProcessLookupError): os.kill(result.data["pid"], signal.SIGTERM) def test_run_reports_a_launch_that_failed_immediately_as_an_error(wayland): result = tools.BY_NAME["run"].invoke( invoke.Runner(), {"argv": ["sh", "-c", "echo 'cannot open display' >&2; exit 1"], "settle_s": 5.0}, ) assert result.is_error assert result.data["error"] == "run_exited" assert "cannot open display" in result.text assert "nothing is on" in result.text @pytest.fixture def wayland(workdir, monkeypatch): """A runtime directory the CLI's `env_for_session` accepts. A real AF_UNIX socket, because that function checks `is_socket()`, and the suite's short-pathed `workdir` because an AF_UNIX address is capped near 108 bytes. """ 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()