"""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. Written out rather than derived #: from the table, because a list derived from the thing it checks cannot #: notice a missing entry. EXPECTED = { # frames -- capturing is an act at a moment, so these stay tools "shot", "record", "run", # lifecycle. The read-only verbs are resources; see MOVED_TO_RESOURCES. "session_start", "session_touch", "session_kill", "session_gc", "session_adopt", "session_container", "session_reconcile", # pointer "pointer_acquire", "pointer_move", "pointer_click", "pointer_scroll", "pointer_down", "pointer_up", "pointer_release", # keyboard "keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up", } #: Verbs that are resources now and must NOT come back as tools. Named, not #: merely absent, so re-adding one is a failure rather than a silent widening #: of the surface mcp-v2 narrowed. MOVED_TO_RESOURCES = { "status", "session_list", "session_status", "session_logs", "pointer_state", } def test_the_acting_verbs_are_tools_and_nothing_else_is(): assert set(tools.BY_NAME) == EXPECTED assert len(tools.TOOLS) == 21 def test_the_read_only_verbs_are_not_tools(): """They are `hhstream://…` resources: the host's context, not the model's acts.""" assert MOVED_TO_RESOURCES.isdisjoint(set(tools.BY_NAME)) # ...and the table that says where each one went covers exactly those five, # so a caller holding a v1 name can be told rather than just refused. assert set(tools.MOVED_TO_RESOURCES) == MOVED_TO_RESOURCES for uri in tools.MOVED_TO_RESOURCES.values(): assert uri.startswith("hhstream://") def test_session_container_stayed_a_tool_because_it_writes(): """With an id the CLI runs `container.reconcile`, so it is not a read.""" assert "session_container" in tools.BY_NAME assert not tools.BY_NAME["session_container"].read_only assert "write" in tools.BY_NAME["session_container"].description 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(): """One left, now that the rest of the reads are resources.""" read_only = {tool.name for tool in tools.TOOLS if tool.read_only} assert read_only == {"shot"} # `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 tools the CLI's own note names as NOT counting as activity. The others #: it names are resources now, and `test_mcp_resources.py` holds those. NON_ACTIVITY = { "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", } #: The four families `--toolsets` selects from. FAMILIES = ("frames", "sessions", "pointer", "keyboard") 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 # It has to name the *resources* now, because that is where reading moved: # an agent told "listing does not count" cannot act on it if the thing it # is listing with is no longer called `session_list`. for named in ("hhstream://sessions", "session_gc", "pointer or keyboard tool"): assert named in tools.ACTIVITY_NOTE assert "does 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", []) # ── toolsets ─────────────────────────────────────────────────────────────── def test_every_tool_is_in_exactly_one_toolset(): """Or `--toolsets` would be able to hide a tool nobody could ask for.""" assert tuple(tools.TOOLSETS) == FAMILIES seen: list[str] = [] for family in FAMILIES: seen.extend(tools.TOOLSETS[family]) assert len(seen) == len(set(seen)), "a tool is in two toolsets" assert set(seen) == set(tools.BY_NAME), "a tool is in no toolset" def test_no_toolset_named_is_every_tool(): """The default, and what an unconfigured client gets.""" assert tools.selected(None) == tools.TOOLS def test_a_selection_keeps_the_table_s_own_order(): """So a listing does not reshuffle because of how the flag was written.""" chosen = [tool.name for tool in tools.selected(["keyboard", "frames"])] assert chosen == ["shot", "record", "run", "keyboard_type", "keyboard_key", "keyboard_down", "keyboard_up"] def test_a_repeated_family_is_not_a_repeated_tool(): assert tools.selected(["frames", "frames"]) == tools.selected(["frames"]) def test_an_unknown_family_is_refused_and_names_the_known_ones(): """Not skipped: a typo that served nothing would look like an empty server.""" with pytest.raises(tools.UnknownToolset) as caught: tools.selected(["frames", "mouse"]) assert "'mouse'" in str(caught.value) for family in FAMILIES: assert family in str(caught.value) 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_gc", {}) assert calls == [["session", "gc", "--json"]] _, calls = call("session_gc", {"request_id": "r-1"}) assert calls == [["session", "gc", "--json", "--request-id=r-1"]] _, calls = call("session_reconcile", {}) assert calls == [["session", "reconcile", "--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_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"]] # ── what each tool makes of the answer ───────────────────────────────────── def test_a_successful_session_verb_passes_the_protocol_object_through(call): reply = {"ok": True, "pruned": 2, "sessions": [{"id": "s-1"}]} result, _ = call("session_gc", {}, 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 "hhstream://pointer" 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_gc", {}, 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()