diff --git a/checks/lib/mcp_client.py b/checks/lib/mcp_client.py index 1fcf56f..9ad3648 100755 --- a/checks/lib/mcp_client.py +++ b/checks/lib/mcp_client.py @@ -14,9 +14,14 @@ things under test, and a client that did it once would prove it once. hhs-mcp-call --initialize the handshake's own result hhs-mcp-call --list every tool, as JSON - hhs-mcp-call session_list one call, no arguments + hhs-mcp-call --resources every resource and template + hhs-mcp-call --read hhstream://sessions one resources/read + hhs-mcp-call session_gc one call, no arguments hhs-mcp-call session_touch '{"id": "s-1"}' one call, arguments as JSON +``--server-arg`` is passed through to the server, which is how a check drives +``--toolsets`` without a second program. + Always exits 0 when the server answered, whatever the answer was: a refusal is a result the test asserts on, not this program's failure. Exit 2 is "the server did not answer" -- it died, it timed out, or it sent something that is @@ -98,7 +103,12 @@ class Server: if answer.get("id") != wanted: fail(f"answer for id {answer.get('id')!r}, expected {wanted}") if "error" in answer: - fail(f"{method} was refused at the protocol level: {answer['error']}") + # Printed as the result and exited 3, not `fail`ed: a resource read + # has no `isError`, so a refusal arrives here -- and the checks + # assert on *which* refusal. Exit 3 keeps it distinguishable from + # exit 2, which is "the server did not answer at all". + print(json.dumps({"error": answer["error"]}, indent=2, sort_keys=True)) + raise SystemExit(3) return answer["result"] def initialize(self) -> dict[str, Any]: @@ -134,9 +144,22 @@ def main(argv: list[str] | None = None) -> int: default="hhstream-mcp", help="the MCP server to spawn (default: %(default)s, from PATH)", ) + parser.add_argument( + "--server-arg", + action="append", + default=[], + metavar="ARG", + help="an argument for the server itself; repeatable", + ) parser.add_argument("--timeout", type=int, default=120, metavar="SECONDS") parser.add_argument("--initialize", action="store_true", help="print the handshake result") parser.add_argument("--list", action="store_true", help="print the tool listing") + parser.add_argument( + "--resources", + action="store_true", + help="print the resource listing and the templates, as one object", + ) + parser.add_argument("--read", metavar="URI", help="read one resource") parser.add_argument("tool", nargs="?", help="the tool to call") parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON") args = parser.parse_args(argv) @@ -151,7 +174,7 @@ def main(argv: list[str] | None = None) -> int: if not isinstance(arguments, dict): fail("arguments must be a JSON object") - server = Server([args.server], args.timeout) + server = Server([args.server, *args.server_arg], args.timeout) try: handshake = server.initialize() if args.initialize: @@ -160,8 +183,33 @@ def main(argv: list[str] | None = None) -> int: if args.list: print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True)) return 0 + if args.resources: + # Both listings as one object, because they are two halves of one + # question and a check that asked twice would pay two handshakes. + print( + json.dumps( + { + "resources": server.request("resources/list")["resources"], + "resourceTemplates": server.request( + "resources/templates/list" + )["resourceTemplates"], + }, + indent=2, + sort_keys=True, + ) + ) + return 0 + if args.read: + print( + json.dumps( + server.request("resources/read", {"uri": args.read}), + indent=2, + sort_keys=True, + ) + ) + return 0 if not args.tool: - fail("name a tool, or pass --list or --initialize") + fail("name a tool, or pass --list, --resources, --read or --initialize") result = server.request( "tools/call", {"name": args.tool, "arguments": arguments} ) diff --git a/checks/vm-mcp.nix b/checks/vm-mcp.nix index 818ee4d..30ec763 100644 --- a/checks/vm-mcp.nix +++ b/checks/vm-mcp.nix @@ -10,11 +10,13 @@ # # WHAT THIS PROVES, AND WHAT IT DOES NOT. # -# It proves the *surface*: the handshake completes over a real pipe, all -# twenty-six tools are listed, a tool call reaches the broker and comes back -# with the broker's own protocol object, an image arrives as image content with -# the geometry the module configured, and a refusal arrives as a tool error -# carrying the frozen exit code rather than as a success. +# It proves the *surface*, both halves of it: the handshake completes over a +# real pipe, all twenty-one tools and all eight resources are listed, a tool +# call reaches the broker and comes back with the broker's own protocol object, +# a resource read reaches it the same way, an image arrives as a blob with the +# geometry the module configured, `--toolsets` actually narrows what is +# offered, and a refusal arrives as a tool error (or, for a resource, a +# protocol error) carrying the frozen exit code rather than as a success. # # It does not prove the compositor behaviour the other checks own, and it must # not be read as doing so. `vm-pointer` is where a click is shown to land in the @@ -148,6 +150,28 @@ testers.runNixOSTest ( return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout) + def read(uri, timeout=180): + """One resources/read that must succeed. Returns its contents list.""" + + return mcp(f"--read {shlex.quote(uri)}", timeout=timeout)["contents"] + + + def read_refused(uri, timeout=180): + """One resources/read that must NOT succeed. Returns the error object. + + A resource read has no `isError`, so a refusal is a protocol error + and the client exits 3 for it -- which is deliberately a different + status from the 2 it uses for "the server did not answer", so this + cannot pass because the server died. + """ + + status, out = machine.execute( + as_user(f"{MCP} --read {shlex.quote(uri)}"), timeout=timeout + ) + assert status == 3, f"expected a refusal (3) for {uri}, got {status}: {out}" + return json.loads(out)["error"] + + def text_of(result): """The text part of a CallToolResult, which is where the CLI's own output and (on a refusal) the remedy live.""" @@ -199,34 +223,75 @@ testers.runNixOSTest ( dump("the mcp handshake") raise - with subtest("tools/list carries every verb, with its annotations"): + with subtest("tools/list carries every acting verb, with its annotations"): listed = mcp("--list")["tools"] names = sorted(tool["name"] for tool in listed) print(f"{len(names)} tools: {', '.join(names)}") - assert len(names) == 26, names + assert len(names) == 21, names for expected in ( - "status", "shot", "record", "run", + "shot", "record", "run", "session_start", "session_touch", "session_kill", "pointer_acquire", "pointer_click", "keyboard_type", ): assert expected in names, f"{expected} is missing from the listing" + # The read-only verbs are resources now and must not be here. + for moved in ("status", "session_list", "session_status", + "session_logs", "pointer_state"): + assert moved not in names, f"{moved} is a resource, not a tool" by_name = {tool["name"]: tool for tool in listed} - assert by_name["session_list"]["annotations"]["readOnlyHint"] is True + assert by_name["shot"]["annotations"]["readOnlyHint"] is True assert by_name["session_kill"]["annotations"]["destructiveHint"] is True - # The rule has to be on the tool, not only in the instructions. - assert "session_touch" in by_name["session_list"]["description"] + # The rules have to be on the tool, not only in the instructions. + assert "session_touch" in by_name["session_gc"]["description"] assert "POINTER lease" in by_name["keyboard_type"]["description"] - with subtest("a read-only tool reaches the broker and returns its object"): + with subtest("resources/list and the templates carry the read-only half"): + both = mcp("--resources") + uris = sorted(r["uri"] for r in both["resources"]) + templates = sorted(t["uriTemplate"] for t in both["resourceTemplates"]) + print(f"resources: {', '.join(uris)}") + print(f"templates: {', '.join(templates)}") + assert uris == [ + "hhstream://containers", + "hhstream://pointer", + "hhstream://screen", + "hhstream://sessions", + "hhstream://status", + ], uris + assert templates == [ + "hhstream://outputs/{name}", + "hhstream://sessions/{id}/logs{?lines}", + "hhstream://sessions/{id}{?events}", + ], templates + by_uri = {r["uri"]: r for r in both["resources"]} + assert by_uri["hhstream://status"]["mimeType"] == "text/plain" + assert by_uri["hhstream://sessions"]["mimeType"] == "application/json" + # The idle-clock rule is on the reads it applies to. + assert "does NOT reset" in by_uri["hhstream://sessions"]["description"] + + with subtest("a resource read reaches the broker and returns its object"): try: - result = succeeded("session_list") - assert result["structuredContent"]["ok"] is True, result - # The text part is the CLI's own `--json` output, unmodified. - assert json.loads(text_of(result)) == result["structuredContent"] + contents = read("hhstream://sessions") + assert len(contents) == 1, contents + assert contents[0]["mimeType"] == "application/json" + # The body is the CLI's own `--json` output, unmodified. + listing = json.loads(contents[0]["text"]) + assert listing["ok"] is True, listing + assert "sessions" in listing, listing except Exception: - dump("session_list over mcp") + dump("reading hhstream://sessions") raise + with subtest("the status resource answers without the broker's help"): + # It reads the compositor's units and the frame socket, not the + # control socket -- which is why it is the thing to read first. + contents = read("hhstream://status") + assert contents[0]["mimeType"] == "text/plain" + report = contents[0]["text"] + print(report) + assert "hyprland-headless.service" in report + assert "frame:" in report + with subtest("a session started over mcp is the broker's own session"): try: started = succeeded("session_start", {"app": "foot"}, timeout=300) @@ -241,23 +306,38 @@ testers.runNixOSTest ( dump("session_start over mcp") raise - with subtest("touch is the verb that moves the idle deadline"): + with subtest("reading a session does not reset its clock; touching it does"): + # The rule the whole surface repeats, measured rather than asserted + # about: two reads of the resource, then the tool, and the deadline + # has to move only for the tool. try: - before = succeeded("session_status", {"id": session_id}) - before_expiry = before["structuredContent"]["session"]["expires_in_s"] - # `status` must NOT have moved it; `touch` must. - after_status = succeeded("session_status", {"id": session_id}) - assert ( - after_status["structuredContent"]["session"]["expires_in_s"] - <= before_expiry - ), "reading status reset the idle clock" + def expires_in(): + body = json.loads(read(f"hhstream://sessions/{session_id}")[0]["text"]) + return body["session"]["expires_in_s"] + + first = expires_in() + second = expires_in() + assert second <= first, ( + f"reading hhstream://sessions/{session_id} reset the idle " + f"clock: {first} -> {second}" + ) touched = succeeded("session_touch", {"id": session_id}) assert ( - touched["structuredContent"]["session"]["expires_in_s"] - >= after_status["structuredContent"]["session"]["expires_in_s"] + touched["structuredContent"]["session"]["expires_in_s"] >= second ), touched except Exception: - dump("touch over mcp", session_id) + dump("the idle clock over mcp", session_id) + raise + + with subtest("a session's logs read through its template, with a query"): + try: + contents = read(f"hhstream://sessions/{session_id}/logs?lines=5") + body = json.loads(contents[0]["text"]) + assert body["ok"] is True, body + assert "lines" in body, body + print(f"{len(body['lines'])} line(s) of {session_id}'s own output") + except Exception: + dump("reading a session's logs", session_id) raise with subtest("shot returns image content, sized as the publisher serves it"): @@ -290,24 +370,50 @@ testers.runNixOSTest ( dump("shot over mcp", session_id) raise - with subtest("shot of the session's own container is one output, exactly"): - # Which is also the only subtest that reads `session_container`, and - # the one that joins the two tools an agent uses together: the - # output name that verb reports is what `shot` takes as `output`. + with subtest("the container is listed as a resource and reconciled as a tool"): + # The pair that has to stay split: the LIST only reads the record, + # so it is a resource; asking where the window is *now* re-reads the + # compositor and writes the answer back, so it is a tool. Both are + # asked here, and they have to agree about the output's name. try: - container = succeeded("session_container", {"id": session_id}) - output = container["structuredContent"]["container"]["output"] - print(f"container output: {output}") - assert output == f"hh-{session_id}", container + listed = json.loads(read("hhstream://containers")[0]["text"]) + assert listed["ok"] is True, listed + from_resource = [ + c["output"] for c in (listed.get("containers") or []) + ] + print(f"containers resource reports: {from_resource}") + assert f"hh-{session_id}" in from_resource, listed + reconciled = succeeded("session_container", {"id": session_id}) + output = reconciled["structuredContent"]["container"]["output"] + assert output == f"hh-{session_id}", reconciled + except Exception: + dump("the container, both ways", session_id) + raise + + with subtest("one output's frame reads as a blob, at exactly its own size"): + # The resource that is an image, and the one place the configured + # geometry is the geometry: `hhstream://screen` is the whole layout. + try: + output = f"hh-{session_id}" + contents = read(f"hhstream://outputs/{output}", timeout=300) + assert len(contents) == 1, contents + blob = contents[0] + assert blob["mimeType"] in ("image/png", "image/jpeg"), blob + assert "text" not in blob, "an image must not arrive as text" + frame = base64.b64decode(blob["blob"]) + print(f"{output}: {blob['mimeType']}, {len(frame)} bytes") + assert frame[:4] in (b"\x89PNG", b"\xff\xd8\xff\xe0") + assert len(frame) > 1024, "a frame that small is not a desktop" + + # And the tool agrees about the size, which is what makes the + # pointer's normalised coordinates meaningful. framed = succeeded("shot", {"output": output}, timeout=300) reported = framed["structuredContent"] print(text_of(framed)) - assert reported["output"] == output, reported assert (reported["width"], reported["height"]) == (WIDTH, HEIGHT), reported - assert framed["content"][1]["type"] == "image" except Exception: - dump("shot --output over mcp", session_id) + dump("reading an output's frame", session_id) raise with subtest("the pointer lease is granted, used and given back"): @@ -347,11 +453,29 @@ testers.runNixOSTest ( assert "exit 9 (NO_LEASE)" in said assert "pointer_acquire" in said - with subtest("an unknown session is exit 3, not a success"): - refused = call("session_status", {"id": "no-such-session"}) + with subtest("an unknown session is exit 3 from a tool, not a success"): + refused = call("session_touch", {"id": "no-such-session"}) assert refused["isError"] is True, refused assert refused["structuredContent"]["exit_code"] == 3, refused - assert "session_list" in text_of(refused) + assert "hhstream://sessions" in text_of(refused) + + with subtest("a refused read is a protocol error carrying the same remedy"): + # A resources/read has no `isError`, so this is the one place the + # refusal has to travel as an error -- with the exit code intact, + # or an agent cannot tell "no such session" from "broker down". + error = read_refused("hhstream://sessions/no-such-session") + print(error["message"].splitlines()[0]) + assert error["data"]["exit_code"] == 3, error + assert error["data"]["error"] == "no_such_session", error + assert "exit 3 (NO_SUCH_SESSION)" in error["message"] + + with subtest("a uri this server does not serve is refused without running anything"): + error = read_refused("hhstream://nonsense") + assert "no resource at" in error["message"], error + # And an undeclared query parameter, which the routing refuses for + # the reason every tool schema sets additionalProperties: false. + error = read_refused("hhstream://pointer?id=x") + assert "accepts: none" in error["message"], error with subtest("an argument the schema refuses never reaches the broker"): # No `lease`, so the server's own schema refuses before an argv list @@ -360,6 +484,44 @@ testers.runNixOSTest ( assert refused["isError"] is True, refused assert "lease" in text_of(refused), refused + with subtest("--toolsets narrows the tools and leaves the resources alone"): + # The flag exists because a tool listing is a budget. What it must + # not do is take the host's context away with it. + narrowed = json.loads( + machine.succeed( + as_user(f"{MCP} --server-arg=--toolsets=keyboard --list"), + timeout=180, + ) + )["tools"] + names = sorted(tool["name"] for tool in narrowed) + print(f"--toolsets keyboard offers: {', '.join(names)}") + assert names == [ + "keyboard_down", "keyboard_key", "keyboard_type", "keyboard_up", + ], names + + still_there = json.loads( + machine.succeed( + as_user(f"{MCP} --server-arg=--toolsets=keyboard --resources"), + timeout=180, + ) + ) + assert len(still_there["resources"]) == 5, still_there + assert len(still_there["resourceTemplates"]) == 3, still_there + + # And a tool outside the selection must be unreachable, not merely + # unlisted, or the flag is cosmetic. + refused = json.loads( + machine.succeed( + as_user( + f"{MCP} --server-arg=--toolsets=keyboard session_kill " + + shlex.quote(json.dumps({"id": session_id})) + ), + timeout=180, + ) + ) + assert refused["isError"] is True, refused + assert "without its toolset" in text_of(refused), refused + with subtest("kill over mcp ends the session the broker was tracking"): try: killed = succeeded("session_kill", {"id": session_id}, timeout=300) diff --git a/tests/unit/test_mcp_invoke.py b/tests/unit/test_mcp_invoke.py index e3fefe7..e9c4503 100644 --- a/tests/unit/test_mcp_invoke.py +++ b/tests/unit/test_mcp_invoke.py @@ -252,7 +252,7 @@ def test_the_lease_codes_say_the_two_different_things_an_agent_must_do(): busy = invoke.remedy_for(int(ExitCode.BUSY)) none_held = invoke.remedy_for(int(ExitCode.NO_LEASE)) - assert "pointer_state" in busy and "wait" in busy + 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. diff --git a/tests/unit/test_mcp_resources.py b/tests/unit/test_mcp_resources.py new file mode 100644 index 0000000..a9b0559 --- /dev/null +++ b/tests/unit/test_mcp_resources.py @@ -0,0 +1,303 @@ +"""The resource table: which URI runs which CLI call, and what comes back. + +Same subject as ``test_mcp_tools.py`` and the same stand-in: what this layer +decides is the argv list, and here also the *routing* -- which entry a URI +resolves to, and which query parameters it will accept. Nothing here imports +the MCP SDK; the protocol wiring is ``test_mcp_server.py``. +""" + +from __future__ import annotations + +import json + +import mcp_fake +import pytest +from hhstreamd.protocol import ExitCode +from hhstream_mcp import invoke, resources, tools + + +@pytest.fixture(autouse=True) +def _isolated(monkeypatch, tmp_path): + mcp_fake.isolate(monkeypatch, tmp_path) + + +@pytest.fixture +def read(): + """`read("hhstream://sessions")` -> (Reading, [argv, ...]).""" + + def _read(uri, **script): + fake = mcp_fake.FakeCli(**script) + reading = resources.read(invoke.Runner(fake), uri) + return reading, fake.calls + + return _read + + +# ── the table ────────────────────────────────────────────────────────────── + +#: Every resource `docs/CONTRACT-mcp.md` §4 freezes, written out rather than +#: derived, for the reason the tool list is. +EXPECTED_FIXED = { + "hhstream://status", + "hhstream://sessions", + "hhstream://pointer", + "hhstream://containers", + "hhstream://screen", +} +EXPECTED_TEMPLATES = { + "hhstream://sessions/{id}{?events}", + "hhstream://sessions/{id}/logs{?lines}", + "hhstream://outputs/{name}", +} + + +def test_the_whole_surface_is_there_and_nothing_else_is(): + assert {entry.uri for entry in resources.FIXED} == EXPECTED_FIXED + assert {entry.uri_template for entry in resources.TEMPLATES} == EXPECTED_TEMPLATES + assert len(resources.ENTRIES) == len(EXPECTED_FIXED) + len(EXPECTED_TEMPLATES) + + +def test_every_entry_has_a_unique_name_and_a_description(): + names = [entry.name for entry in resources.ENTRIES] + assert len(names) == len(set(names)) + for entry in resources.ENTRIES: + assert entry.title, entry.name + assert len(entry.description) > 40, entry.name + assert entry.media_type + + +def test_a_template_is_exactly_an_entry_with_a_capture(): + for entry in resources.FIXED: + assert entry.captures == () + for entry in resources.TEMPLATES: + assert entry.captures + + +def test_the_three_reads_the_activity_rule_names_say_so_themselves(): + """The rule has to be where it is read, and these are read, not called.""" + + for name in ("sessions", "session", "session-logs", "pointer", "containers"): + description = resources.BY_NAME[name].description + assert "does NOT reset" in description, name + assert "`session_touch`" in description, name + + +# ── routing ──────────────────────────────────────────────────────────────── + + +def test_a_literal_route_beats_a_template_that_would_also_match(): + """`hhstream://sessions` is the listing, not a session with a blank id.""" + + entry, arguments = resources.resolve("hhstream://sessions") + assert entry.name == "sessions" + assert arguments == {} + + +def test_a_capture_becomes_the_argument_the_cli_takes(read): + _, calls = read("hhstream://sessions/foot-abc", stdout=mcp_fake.reply(ok=True)) + assert calls == [["session", "status", "--json", "--", "foot-abc"]] + + +def test_a_deeper_route_is_its_own_entry(read): + _, calls = read("hhstream://sessions/foot-abc/logs", stdout=mcp_fake.reply(ok=True)) + assert calls == [["session", "logs", "--json", "--", "foot-abc"]] + + +def test_each_fixed_resource_runs_the_verb_it_names(read): + cases = { + "hhstream://status": ["status"], + "hhstream://sessions": ["session", "list", "--json"], + "hhstream://pointer": ["session", "pointer", "state", "--json"], + "hhstream://containers": ["session", "container", "--json"], + } + for uri, argv in cases.items(): + _, calls = read(uri, stdout=mcp_fake.reply(ok=True)) + assert calls == [argv], uri + + +def test_the_status_resource_is_text_because_the_verb_has_no_json(read): + reading, calls = read("hhstream://status", stdout="services:\n up\n") + assert calls == [["status"]] + assert reading.media_type == "text/plain" + assert reading.text == "services:\n up" + assert reading.blob is None + + +def test_a_json_resource_passes_the_protocol_object_through_unchanged(read): + reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]} + reading, _ = read("hhstream://sessions", stdout=json.dumps(reply, indent=2)) + + assert reading.media_type == "application/json" + assert json.loads(reading.text) == reply + + +def test_a_scheme_this_server_does_not_serve_is_refused(read): + with pytest.raises(resources.ReadRefused) as caught: + read("file:///etc/passwd") + assert "not a hhstream resource" in str(caught.value) + + +def test_a_uri_that_names_nothing_is_refused_and_points_at_the_listing(read): + for uri in ("hhstream://nonsense", "hhstream://sessions/a/b/c", "hhstream://"): + with pytest.raises(resources.ReadRefused) as caught: + read(uri) + assert "resources/list" in str(caught.value) or "names no resource" in str( + caught.value + ) + + +def test_nothing_was_run_for_a_uri_that_did_not_resolve(monkeypatch, tmp_path): + """The routing refuses before the CLI is reached, as a schema would.""" + + fake = mcp_fake.FakeCli() + with pytest.raises(resources.ReadRefused): + resources.read(invoke.Runner(fake), "hhstream://nonsense") + assert fake.calls == [] + + +# ── query parameters ─────────────────────────────────────────────────────── + + +def test_a_declared_parameter_becomes_the_flag_the_cli_takes(read): + _, calls = read( + "hhstream://sessions/foot-abc/logs?lines=250", stdout=mcp_fake.reply(ok=True) + ) + assert calls == [["session", "logs", "--json", "--lines=250", "--", "foot-abc"]] + + _, calls = read( + "hhstream://sessions/foot-abc?events=5", stdout=mcp_fake.reply(ok=True) + ) + assert calls == [["session", "status", "--json", "--events=5", "--", "foot-abc"]] + + +def test_a_switch_parameter_is_a_bare_flag_or_nothing(read): + """`--all=false` is not a thing the CLI takes, so false must omit it.""" + + _, calls = read("hhstream://sessions?all=true", stdout=mcp_fake.reply(ok=True)) + assert calls == [["session", "list", "--json", "--all"]] + + for falsey in ("false", "0", "no", "off", ""): + _, calls = read(f"hhstream://sessions?all={falsey}", stdout=mcp_fake.reply(ok=True)) + assert calls == [["session", "list", "--json"]], falsey + + +def test_an_undeclared_parameter_is_refused_rather_than_dropped(read): + """A parameter silently ignored is a read that answered another question.""" + + with pytest.raises(resources.ReadRefused) as caught: + read("hhstream://sessions?lines=5") + assert "'lines'" in str(caught.value) + assert "all" in str(caught.value) + + +def test_a_resource_with_no_parameters_says_so_when_given_one(read): + with pytest.raises(resources.ReadRefused) as caught: + read("hhstream://pointer?id=s-1") + assert "accepts: none" in str(caught.value) + + +def test_a_parameter_given_twice_is_refused(read): + with pytest.raises(resources.ReadRefused) as caught: + read("hhstream://sessions/s-1/logs?lines=1&lines=2") + assert "more than once" in str(caught.value) + + +def test_the_template_advertises_the_parameters_it_accepts(): + """So a client can construct a URI without guessing.""" + + logs = resources.BY_NAME["session-logs"] + assert logs.uri_template == "hhstream://sessions/{id}/logs{?lines}" + assert logs.parameters == ("lines",) + + +# ── refusals ─────────────────────────────────────────────────────────────── + + +def test_a_cli_refusal_is_raised_and_never_returned_as_the_body(read): + """A resource has no `isError`; returning the failure object would lie.""" + + reply = {"ok": False, "error": "no_such_session", "reason": "no session 'nope'"} + with pytest.raises(resources.ReadRefused) as caught: + read( + "hhstream://sessions/nope", + stderr=mcp_fake.reply(**reply), + exit_code=int(ExitCode.NO_SUCH_SESSION), + ) + refused = caught.value + assert "exit 3 (NO_SUCH_SESSION)" in refused.message + assert "no session 'nope'" in refused.message + # And the structured detail carries what a tool error would have carried. + assert refused.detail["exit_code"] == int(ExitCode.NO_SUCH_SESSION) + assert refused.detail["error"] == "no_such_session" + assert "hhstream://sessions" in refused.detail["remedy"] + + +def test_an_unreachable_broker_is_refused_with_the_operator_s_remedy(read): + with pytest.raises(resources.ReadRefused) as caught: + read( + "hhstream://sessions", + stderr=mcp_fake.reply(ok=False, error="daemon_unreachable", reason="no socket"), + exit_code=int(ExitCode.DAEMON_UNREACHABLE), + ) + assert "HHSTREAM_SOCKET" in caught.value.message + + +# ── frames ───────────────────────────────────────────────────────────────── + + +def test_the_screen_resource_is_the_frame_bytes_with_its_real_media_type(read): + frame = mcp_fake.png(width=320, height=180) + reading, calls = read("hhstream://screen", write_png=frame) + + assert calls[0][0] == "shot" + assert calls[0][1].startswith("--out=") + assert len(calls[0]) == 2, "the screen takes no --output" + assert reading.blob == frame + assert reading.text is None + assert reading.media_type == "image/png" + + +def test_an_output_resource_captures_that_output_alone(read): + frame = mcp_fake.png() + reading, calls = read("hhstream://outputs/hh-foot-abc", write_png=frame) + + assert "--output=hh-foot-abc" in calls[0] + assert reading.blob == frame + + +def test_a_frame_s_media_type_is_sniffed_and_not_assumed(read): + """The entry declares image/png; a JPEG publisher must still be told truly.""" + + assert resources.BY_NAME["screen"].media_type == "image/png" + reading, _ = read("hhstream://screen", write_png=mcp_fake.jpeg()) + assert reading.media_type == "image/jpeg" + + +def test_a_capture_that_wrote_no_file_is_refused_rather_than_empty(read): + with pytest.raises(resources.ReadRefused) as caught: + read("hhstream://screen") + assert "no readable file" in str(caught.value) + + +def test_a_refused_capture_carries_the_cli_s_own_words(read): + with pytest.raises(resources.ReadRefused) as caught: + read( + "hhstream://outputs/hh-gone", + stderr="hhstream: could not capture output 'hh-gone': unknown output\n", + exit_code=1, + ) + assert "unknown output" in str(caught.value) + assert "hh-gone" in str(caught.value) + + +# ── the one read that must not be a resource ─────────────────────────────── + + +def test_there_is_no_resource_for_the_reconciling_container_read(): + """`session container ` writes. Only the no-id list is a resource.""" + + assert "hhstream://containers" in EXPECTED_FIXED + for entry in resources.ENTRIES: + assert entry.route[:1] != ("containers",) or entry.captures == () + # ...and the writing form is still reachable, as a tool. + assert "session_container" in tools.BY_NAME diff --git a/tests/unit/test_mcp_server.py b/tests/unit/test_mcp_server.py index b564a67..5b04d24 100644 --- a/tests/unit/test_mcp_server.py +++ b/tests/unit/test_mcp_server.py @@ -28,8 +28,9 @@ import pytest from hhstreamd.protocol import ExitCode from mcp.shared.memory import create_connected_server_and_client_session from mcp.shared.tool_name_validation import validate_tool_name +from pydantic import AnyUrl -from hhstream_mcp import SERVER_NAME, __version__, invoke, server, tools +from hhstream_mcp import SERVER_NAME, __version__, invoke, resources, server, tools @pytest.fixture(autouse=True) @@ -47,9 +48,9 @@ def session(): about. """ - def _session(**script): + def _session(toolsets=None, **script): fake = mcp_fake.FakeCli(**script) - built = server.build(invoke.Runner(fake)) + built = server.build(invoke.Runner(fake), toolsets) return fake, create_connected_server_and_client_session( built, raise_exceptions=True ) @@ -76,6 +77,9 @@ def test_initialize_names_this_server_and_declares_tools(session): assert initialized.serverInfo.name == SERVER_NAME assert initialized.serverInfo.version == __version__ assert initialized.capabilities.tools is not None + # Resources are half the surface now, so the capability has to be declared + # or a host will never ask for them. + assert initialized.capabilities.resources is not None # The instructions are where the two rules are said once for the whole # surface; a client that shows them must be given them. assert initialized.instructions @@ -91,6 +95,15 @@ def test_the_instructions_carry_both_rules(): assert "9 means you need to acquire one" in server.INSTRUCTIONS +def test_the_instructions_explain_the_split_they_cannot_be_read_without(): + """An agent that does not know state is a resource will look for a tool.""" + + assert "Resources are the state" in server.INSTRUCTIONS + assert "Tools are the acts" in server.INSTRUCTIONS + for uri in ("hhstream://status", "hhstream://sessions", "hhstream://pointer"): + assert uri in server.INSTRUCTIONS + + # ── the listing ──────────────────────────────────────────────────────────── @@ -104,6 +117,7 @@ def test_tools_list_returns_every_tool_with_a_title_and_a_description(session): listed = run(go).tools assert {tool.name for tool in listed} == set(tools.BY_NAME) + assert len(listed) == 21 for tool in listed: assert tool.title, tool.name assert tool.description and len(tool.description) > 40, tool.name @@ -186,18 +200,18 @@ def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session): def test_a_successful_call_carries_the_protocol_object_as_structured_content(session): - reply = {"ok": True, "sessions": []} + reply = {"ok": True, "pruned": 0} fake, connected = session(stdout=json.dumps(reply, indent=2)) async def go(): async with connected as client: await client.initialize() - return await client.call_tool("session_list", {}) + return await client.call_tool("session_gc", {}) result = run(go) assert not result.isError assert result.structuredContent == reply - assert fake.calls == [["session", "list", "--json"]] + assert fake.calls == [["session", "gc", "--json"]] def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session): @@ -243,6 +257,24 @@ def test_a_frame_arrives_as_image_content_beside_its_geometry(session): assert base64.b64decode(image.data) == frame +def test_a_v1_tool_name_is_told_which_resource_replaced_it(session): + """`no such tool` alone reads as a broken server rather than a moved surface.""" + + fake, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("session_list", {}) + + result = run(go) + assert result.isError is True + text = result.content[0].text + assert "It is a RESOURCE now" in text + assert "hhstream://sessions" in text + assert fake.calls == [] + + def test_a_tool_that_does_not_exist_names_the_ones_that_do(session): """And is an error. The SDK turns a raised McpError into this shape anyway.""" @@ -264,7 +296,7 @@ def test_a_handler_that_raises_is_reported_to_the_agent_and_not_only_logged(): """A CLI process would have died with a traceback and status 1; so does this.""" fake = mcp_fake.FakeCli(raises=RuntimeError("the broker said something odd")) - result = server.call(invoke.Runner(fake), "session_list", {}) + result = server.call(invoke.Runner(fake), "session_gc", {}) assert result.isError is True assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE @@ -306,6 +338,192 @@ def test_the_listing_is_what_the_entry_point_prints(capsys): assert printed[0].split("\t")[0] == tools.TOOLS[0].name +def test_the_entry_point_lists_resources_too(capsys): + assert server.main(["--list-resources"]) == 0 + printed = capsys.readouterr().out.splitlines() + assert len(printed) == len(resources.ENTRIES) + assert printed[0].split("\t")[0] == "hhstream://status" + + +def test_the_entry_point_s_listing_honours_a_toolset_selection(capsys): + assert server.main(["--list-tools", "--toolsets", "keyboard"]) == 0 + printed = capsys.readouterr().out.splitlines() + assert [line.split("\t")[0] for line in printed] == list( + tools.TOOLSETS["keyboard"] + ) + + +def test_an_unknown_toolset_on_the_command_line_is_argparse_s_exit_two(capsys): + with pytest.raises(SystemExit) as caught: + server.main(["--list-tools", "--toolsets", "mouse"]) + assert caught.value.code == 2 + assert "no such toolset" in capsys.readouterr().err + + +def test_an_empty_toolset_list_is_refused_rather_than_read_as_all(capsys): + """`--toolsets ""` is a mistake, and serving everything would hide it.""" + + with pytest.raises(SystemExit) as caught: + server.main(["--list-tools", "--toolsets", " , "]) + assert caught.value.code == 2 + + +# ── resources, over the protocol ─────────────────────────────────────────── + + +def test_resources_list_returns_the_fixed_ones_with_their_descriptions(session): + _, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.list_resources() + + listed = run(go).resources + assert {str(r.uri) for r in listed} == {e.uri for e in resources.FIXED} + for resource in listed: + assert resource.title and resource.description and resource.mimeType + + +def test_resource_templates_are_listed_separately_with_their_parameters(session): + _, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + return await client.list_resource_templates() + + listed = run(go).resourceTemplates + assert {t.uriTemplate for t in listed} == {e.uri_template for e in resources.TEMPLATES} + logs = next(t for t in listed if t.uriTemplate.endswith("/logs{?lines}")) + assert logs.name == "session-logs" + + +def test_reading_a_json_resource_returns_the_broker_s_object(session): + reply = {"ok": True, "sessions": [{"id": "s-1", "state": "running"}]} + fake, connected = session(stdout=json.dumps(reply, indent=2)) + + async def go(): + async with connected as client: + await client.initialize() + return await client.read_resource(AnyUrl("hhstream://sessions")) + + result = run(go) + assert len(result.contents) == 1 + content = result.contents[0] + assert content.mimeType == "application/json" + assert json.loads(content.text) == reply + assert fake.calls == [["session", "list", "--json"]] + + +def test_reading_a_template_passes_the_capture_and_the_query_through(session): + fake, connected = session(stdout=mcp_fake.reply(ok=True, lines=[])) + + async def go(): + async with connected as client: + await client.initialize() + return await client.read_resource( + AnyUrl("hhstream://sessions/foot-abc/logs?lines=7") + ) + + run(go) + assert fake.calls == [ + ["session", "logs", "--json", "--lines=7", "--", "foot-abc"] + ] + + +def test_reading_a_frame_resource_returns_a_blob_not_text(session): + frame = mcp_fake.png(width=48, height=24) + _, connected = session(write_png=frame) + + async def go(): + async with connected as client: + await client.initialize() + return await client.read_resource(AnyUrl("hhstream://screen")) + + content = run(go).contents[0] + assert isinstance(content, types.BlobResourceContents) + assert content.mimeType == "image/png" + + import base64 + + assert base64.b64decode(content.blob) == frame + + +def test_a_refused_read_is_a_protocol_error_carrying_the_remedy(session): + """A resource read has no `isError`, so the refusal has to be an error.""" + + from mcp.shared.exceptions import McpError + + fake, connected = session( + stderr=mcp_fake.reply(ok=False, error="no_such_session", reason="no session 'nope'"), + exit_code=int(ExitCode.NO_SUCH_SESSION), + ) + + async def go(): + async with connected as client: + await client.initialize() + with pytest.raises(McpError) as caught: + await client.read_resource(AnyUrl("hhstream://sessions/nope")) + return caught.value + + error = run(go) + assert "exit 3 (NO_SUCH_SESSION)" in str(error) + assert "no session 'nope'" in str(error) + + +def test_a_uri_that_names_no_resource_is_a_protocol_error(session): + from mcp.shared.exceptions import McpError + + fake, connected = session() + + async def go(): + async with connected as client: + await client.initialize() + with pytest.raises(McpError) as caught: + await client.read_resource(AnyUrl("hhstream://nonsense")) + return caught.value + + error = run(go) + assert "no resource at" in str(error) + assert fake.calls == [] + + +# ── toolsets, over the protocol ──────────────────────────────────────────── + + +def test_a_toolset_selection_narrows_the_listing_but_not_the_resources(session): + _, connected = session(toolsets=["keyboard"]) + + async def go(): + async with connected as client: + await client.initialize() + return await client.list_tools(), await client.list_resources() + + listed, resource_list = run(go) + assert [t.name for t in listed.tools] == list(tools.TOOLSETS["keyboard"]) + # Resources are the host's context, not the model's tool budget. + assert len(resource_list.resources) == len(resources.FIXED) + + +def test_a_tool_outside_the_selection_cannot_be_called_by_name(session): + """Unlisted must mean unreachable, or the selection is cosmetic.""" + + fake, connected = session(toolsets=["keyboard"]) + + async def go(): + async with connected as client: + await client.initialize() + return await client.call_tool("session_kill", {"id": "s-1"}) + + result = run(go) + assert result.isError is True + text = result.content[0].text + assert "session_kill" in text + assert "without its toolset" in text + assert fake.calls == [] + + def test_content_for_a_text_only_result_has_no_image_block(): blocks = server.content_for(tools.Result(text="hello")) assert [block.type for block in blocks] == ["text"] diff --git a/tests/unit/test_mcp_tools.py b/tests/unit/test_mcp_tools.py index 8e66a21..6733d8c 100644 --- a/tests/unit/test_mcp_tools.py +++ b/tests/unit/test_mcp_tools.py @@ -42,26 +42,56 @@ def 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. +#: 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 - "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", + # 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", "pointer_state", + "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_every_cli_verb_has_a_tool_and_nothing_else_does(): + +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(): @@ -71,18 +101,10 @@ def test_the_table_is_ordered_and_has_no_duplicate_names(): def test_only_the_verbs_that_read_are_marked_read_only(): - """`session_container` with an id reconciles, which is a write.""" + """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 == { - "status", - "shot", - "session_list", - "session_status", - "session_logs", - "pointer_state", - } - assert not tools.BY_NAME["session_container"].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 @@ -91,12 +113,9 @@ def test_only_the_verbs_that_read_are_marked_read_only(): # ── 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. +#: 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_list", - "session_status", - "session_logs", "session_gc", "session_container", "session_reconcile", @@ -115,6 +134,9 @@ GESTURES = { "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"}: @@ -124,9 +146,12 @@ def test_the_idle_clock_rule_is_on_every_tool_that_does_not_reset_it(): 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 + # 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(): @@ -170,6 +195,48 @@ def test_the_lease_is_a_required_argument_on_every_gesture_and_is_never_cached() 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 @@ -187,12 +254,12 @@ def test_a_session_verb_is_run_with_json_and_its_id_after_a_separator(call): 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"]] + _, 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): @@ -259,12 +326,6 @@ def test_a_negative_scroll_amount_stays_one_token(call): ] -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}) @@ -288,23 +349,12 @@ def test_container_with_no_id_lists_and_with_an_id_reconciles(call): 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)) + 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 @@ -366,7 +416,7 @@ def test_the_contended_lease_case_names_the_holder_and_does_not_say_acquire(call assert result.is_error assert result.text.startswith("exit 8 (BUSY)") - assert "pointer_state" in result.text + assert "hhstream://pointer" in result.text assert "s-other" in result.text @@ -387,7 +437,7 @@ def test_a_usage_refusal_from_argparse_itself_is_still_an_error(call): def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call): result, _ = call( - "session_list", + "session_gc", {}, stderr="error: cannot reach the hhstream session daemon at /run/hhstream/control.sock\n", exit_code=int(ExitCode.DAEMON_UNREACHABLE), @@ -395,7 +445,7 @@ def test_a_broker_that_is_down_is_reported_as_the_operator_s_problem(call): assert result.is_error assert "HHSTREAM_SOCKET" in result.text - assert "Frame tools" in result.text + assert "frame tools" in result.text # ── shot and record ────────────────────────────────────────────────────────