101 unit tests under `tests/unit/` and one new VM check. The unit suite's subject is the only thing this layer decides: the argv list. `mcp_fake.FakeCli` is a recording stand-in put where the CLI goes, so every test can assert on the exact argv a tool handed over -- the `=` form of each flag, the `--` before each positional, the omission of a flag the caller did not give. Three tests drive the **real** entry point against a control socket that does not exist, which proves the dispatch, the capture and the exit-code mapping against the CLI's actual parser with no daemon standing up: argparse's exit 2 for a bad `--button`, exit 5 for the unreachable broker, exit 9 for a gesture with no lease. `test_mcp_server.py` imports the MCP SDK unconditionally and runs the server in process over the SDK's memory transport. It is not allowed to skip: the tool table is stdlib and tested without the SDK, but whether every schema validates and every name is one the specification allows is a question only the SDK can answer, and a file that skipped when it was absent would be green in exactly the build where that mattered. `checks/unit.nix` therefore puts `mcp` in the test environment and `hhstream-mcp` on PYTHONPATH beside `hhstream`. `checks/vm-mcp.nix` boots the session machine with `mcp.enable = true` and drives the real binary over a real pipe with `checks/lib/mcp_client.py` -- raw JSON-RPC, deliberately not the SDK's client, for the reason `tests/assert_stream.py` is a second implementation of the frame contract. It asserts the handshake, the 26-tool listing with its annotations and its two rules, a call that reaches the live broker, `shot` as image content, the lease granted/used/returned against the real driver, and exits 9 and 3 arriving as tool errors. The geometry assertion in that check is one it got wrong first time and now records: the published frame is 2560x720 on a guest configured for 1280x720, because the publisher's default capture takes the whole compositor layout and a session's container is a second output beside the main one. `shot` with the container's own `output` is the one that is exactly 1280x720. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE
376 lines
17 KiB
Nix
376 lines
17 KiB
Nix
# checks.<system>.vm-mcp -- the MCP server over stdio, in a guest, against a
|
|
# live broker and a real compositor.
|
|
#
|
|
# The same machine the other session checks use (`lib/session-machine.nix`),
|
|
# plus `services.hyprland-headless-stream.mcp.enable = true` -- which is also
|
|
# the first thing asserted, because "installing it" is the whole of that
|
|
# option. Then `hhs-mcp-call` (`lib/mcp_client.py`) spawns `hhstream-mcp` as the
|
|
# operator account and talks raw JSON-RPC to it: initialize, tools/list,
|
|
# tools/call.
|
|
#
|
|
# 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 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
|
|
# window it was aimed at; `vm-keyboard` is where a typed symbol is shown to be
|
|
# decoded by a client from the keymap the driver uploaded. Here the victim is
|
|
# `foot`, which ignores `$HHSTREAM_APP_ID` and so matches no container rule
|
|
# (README.dev.md, known gap 4) -- so what the pointer and keyboard subtests
|
|
# below assert is that the lease was granted and the driver accepted the
|
|
# injection, which is the part the MCP layer is responsible for.
|
|
#
|
|
# The client is not the MCP SDK's, deliberately: the SDK on both ends would
|
|
# agree with itself about a framing neither side had to get right. Same choice
|
|
# as `tests/assert_stream.py` being a second implementation of the frame
|
|
# contract, and for the same reason.
|
|
#
|
|
# Habits copied from the other session checks: every wait is bounded, each
|
|
# subtest asserts once, and a failure dumps the compositor's diagnostics and
|
|
# the broker's journal before it propagates.
|
|
{
|
|
testers,
|
|
hhstream,
|
|
hhstream-mcp,
|
|
hhsModule,
|
|
testTools,
|
|
hyprland,
|
|
foot,
|
|
jq,
|
|
grim,
|
|
procps,
|
|
coreutils,
|
|
dejavu_fonts,
|
|
width ? 1280,
|
|
height ? 720,
|
|
sessionUser ? "hermes",
|
|
}:
|
|
testers.runNixOSTest (
|
|
{ pkgs, ... }:
|
|
let
|
|
tools = pkgs.callPackage ./lib/session-tools.nix { inherit hhstream; };
|
|
guest = import ./lib/session-machine.nix {
|
|
inherit
|
|
hhsModule
|
|
hhstream
|
|
hyprland
|
|
testTools
|
|
foot
|
|
jq
|
|
procps
|
|
grim
|
|
coreutils
|
|
dejavu_fonts
|
|
;
|
|
sessionTools = tools;
|
|
};
|
|
prelude = import ./lib/session-prelude.nix {
|
|
inherit hhstream coreutils sessionUser;
|
|
};
|
|
|
|
# The client, with a plain python3: it speaks JSON-RPC over a pipe and
|
|
# imports nothing but the standard library, which is what makes it a second
|
|
# implementation rather than the SDK talking to itself.
|
|
client = pkgs.runCommandLocal "hhs-mcp-call" { } ''
|
|
install -Dm755 ${./lib/mcp_client.py} $out/bin/hhs-mcp-call
|
|
sed -i '1s|.*|#!${pkgs.python3}/bin/python3|' $out/bin/hhs-mcp-call
|
|
$out/bin/hhs-mcp-call --help > /dev/null
|
|
# It must refuse to invent a request rather than printing nothing: a
|
|
# client that exits 0 having done nothing would make every subtest below
|
|
# vacuous.
|
|
if $out/bin/hhs-mcp-call --server ${coreutils}/bin/true; then
|
|
echo "hhs-mcp-call succeeded against a server that says nothing" >&2
|
|
exit 1
|
|
fi
|
|
'';
|
|
in
|
|
{
|
|
name = "hhstream-vm-mcp";
|
|
|
|
globalTimeout = 1800;
|
|
|
|
nodes.machine = {
|
|
imports = [
|
|
(guest {
|
|
inherit width height sessionUser;
|
|
pointer = true;
|
|
apps.foot = {
|
|
exec = "${foot}/bin/foot";
|
|
# The broker refuses unlisted arguments and this check passes none:
|
|
# `foot` with no argv opens a window, which is all the victim has
|
|
# to do.
|
|
argsAllow = [ ];
|
|
};
|
|
})
|
|
];
|
|
|
|
# The option under test. Installing the package IS the option, so the
|
|
# first subtest asserts the binary is on PATH and nothing else had to
|
|
# happen.
|
|
services.hyprland-headless-stream.mcp = {
|
|
enable = true;
|
|
package = hhstream-mcp;
|
|
};
|
|
|
|
environment.systemPackages = [ client ];
|
|
};
|
|
|
|
testScript =
|
|
prelude
|
|
+ ''
|
|
import base64
|
|
import shlex
|
|
|
|
MCP = "${client}/bin/hhs-mcp-call"
|
|
WIDTH = ${toString width}
|
|
HEIGHT = ${toString height}
|
|
|
|
|
|
def mcp(argv, timeout=180):
|
|
"""`hhs-mcp-call …` as USER, parsed. Fails loudly if it printed no JSON."""
|
|
|
|
out = machine.succeed(as_user(f"{MCP} {argv}"), timeout=timeout)
|
|
try:
|
|
return json.loads(out)
|
|
except json.JSONDecodeError:
|
|
raise AssertionError(f"not JSON from `hhs-mcp-call {argv}`: {out!r}")
|
|
|
|
|
|
def call(tool, arguments=None, timeout=180):
|
|
"""One tools/call. Returns the CallToolResult as a dict."""
|
|
|
|
payload = json.dumps(arguments or {})
|
|
return mcp(f"{tool} {shlex.quote(payload)}", timeout=timeout)
|
|
|
|
|
|
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."""
|
|
|
|
for block in result.get("content") or []:
|
|
if block.get("type") == "text":
|
|
return block["text"]
|
|
raise AssertionError(f"no text content in {result!r}")
|
|
|
|
|
|
def succeeded(tool, arguments=None, timeout=180):
|
|
"""A call that must not be an error, with the reason printed if it is."""
|
|
|
|
result = call(tool, arguments, timeout=timeout)
|
|
if result.get("isError"):
|
|
print(f"----- {tool} returned an error -----")
|
|
print(text_of(result))
|
|
assert not result.get("isError"), f"{tool} failed: {text_of(result)}"
|
|
return result
|
|
|
|
|
|
start_all()
|
|
bring_up("the compositor and broker")
|
|
|
|
with subtest("the as-user wrapper propagates exit status"):
|
|
# Every assertion below reads machine.succeed through it, so a
|
|
# wrapper that swallowed the status would make them all vacuous.
|
|
machine.succeed(as_user(TRUE), timeout=120)
|
|
machine.fail(as_user(FALSE), timeout=120)
|
|
|
|
with subtest("mcp.enable put the server on the system PATH"):
|
|
# The whole of the module option: no unit, no socket, no state dir.
|
|
path = machine.succeed(as_user("/run/current-system/sw/bin/sh -c 'command -v hhstream-mcp'")).strip()
|
|
print(f"hhstream-mcp resolves to {path}")
|
|
assert path.startswith("/run/current-system/sw/bin"), path
|
|
machine.fail("systemctl is-active hhstream-mcp.service")
|
|
|
|
with subtest("the stdio handshake completes and names this server"):
|
|
try:
|
|
handshake = mcp("--initialize")
|
|
print(json.dumps(handshake, indent=2)[:600])
|
|
assert handshake["serverInfo"]["name"] == "hhstream", handshake
|
|
assert handshake["capabilities"].get("tools") is not None, handshake
|
|
# The two rules, in the instructions a client is handed once.
|
|
instructions = handshake["instructions"]
|
|
assert "`session_touch` is the ONLY" in instructions
|
|
assert "POINTER lease" in instructions
|
|
except Exception:
|
|
dump("the mcp handshake")
|
|
raise
|
|
|
|
with subtest("tools/list carries every 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
|
|
for expected in (
|
|
"status", "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"
|
|
by_name = {tool["name"]: tool for tool in listed}
|
|
assert by_name["session_list"]["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"]
|
|
assert "POINTER lease" in by_name["keyboard_type"]["description"]
|
|
|
|
with subtest("a read-only tool 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"]
|
|
except Exception:
|
|
dump("session_list over mcp")
|
|
raise
|
|
|
|
with subtest("a session started over mcp is the broker's own session"):
|
|
try:
|
|
started = succeeded("session_start", {"app": "foot"}, timeout=300)
|
|
session_id = started["structuredContent"]["id"]
|
|
print(f"started {session_id}")
|
|
assert text_of(started).startswith(f"session id: {session_id}")
|
|
# The broker is the authority on whether that happened, so it
|
|
# is asked directly rather than through the server under test.
|
|
listing = cli_json("list --json")
|
|
assert session_id in [s["id"] for s in listing["sessions"]], listing
|
|
except Exception:
|
|
dump("session_start over mcp")
|
|
raise
|
|
|
|
with subtest("touch is the verb that moves the idle deadline"):
|
|
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"
|
|
touched = succeeded("session_touch", {"id": session_id})
|
|
assert (
|
|
touched["structuredContent"]["session"]["expires_in_s"]
|
|
>= after_status["structuredContent"]["session"]["expires_in_s"]
|
|
), touched
|
|
except Exception:
|
|
dump("touch over mcp", session_id)
|
|
raise
|
|
|
|
with subtest("shot returns image content, sized as the publisher serves it"):
|
|
# MEASURED, and not what this check first assumed: the frame is
|
|
# 2560x720 on a guest configured for 1280x720. The publisher's
|
|
# default capture is `grim -t png -` with no `-o`, which takes the
|
|
# whole compositor layout -- and with containers on (the module's
|
|
# default) a session's own output sits beside the main one, so one
|
|
# session doubles the width. The geometry the module configures is
|
|
# the geometry of an *output*, which is what the next subtest
|
|
# captures by name.
|
|
try:
|
|
shot = succeeded("shot", timeout=300)
|
|
kinds = [block["type"] for block in shot["content"]]
|
|
assert kinds == ["text", "image"], kinds
|
|
image = shot["content"][1]
|
|
frame = base64.b64decode(image["data"])
|
|
print(f"{image['mimeType']}, {len(frame)} bytes: {text_of(shot)}")
|
|
assert image["mimeType"] in ("image/png", "image/jpeg")
|
|
# The media type is read off the bytes, never off the extension
|
|
# this server asked the CLI for -- so the two must agree.
|
|
magic = {"image/png": b"\x89PNG", "image/jpeg": b"\xff\xd8\xff"}
|
|
assert frame.startswith(magic[image["mimeType"]]), frame[:8]
|
|
reported = shot["structuredContent"]
|
|
assert reported["height"] == HEIGHT, reported
|
|
assert reported["width"] >= WIDTH, reported
|
|
assert reported["bytes"] == len(frame), reported
|
|
assert len(frame) > 1024, "a frame that small is not a desktop"
|
|
except Exception:
|
|
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`.
|
|
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
|
|
|
|
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)
|
|
raise
|
|
|
|
with subtest("the pointer lease is granted, used and given back"):
|
|
try:
|
|
acquired = succeeded("pointer_acquire", {"id": session_id})
|
|
lease = acquired["structuredContent"]["lease_id"]
|
|
print(f"lease {lease}: {text_of(acquired).splitlines()[0]}")
|
|
assert text_of(acquired).startswith(f"lease_id: {lease}")
|
|
|
|
# Every gesture takes the lease as an explicit argument: the
|
|
# server caches nothing, which is what makes a transcript of
|
|
# tool calls readable.
|
|
succeeded("pointer_move", {"id": session_id, "lease": lease, "to": [0.5, 0.5]})
|
|
succeeded("pointer_click", {"id": session_id, "lease": lease})
|
|
succeeded("keyboard_type", {"id": session_id, "lease": lease, "text": "hello"})
|
|
typed = succeeded(
|
|
"keyboard_key", {"id": session_id, "lease": lease, "name": "Return"}
|
|
)
|
|
assert typed["structuredContent"]["ok"] is True, typed
|
|
|
|
released = succeeded("pointer_release", {"id": session_id, "lease": lease})
|
|
assert released["structuredContent"]["ok"] is True, released
|
|
# And the broker agrees that nobody holds it now.
|
|
assert cli_json("pointer state --json")["holder"] is None
|
|
except Exception:
|
|
dump("the pointer lease over mcp", session_id)
|
|
raise
|
|
|
|
with subtest("a gesture after the release is exit 9 and says to acquire"):
|
|
# The frozen NO_LEASE code, arriving as a tool error an agent can
|
|
# act on rather than as a success with a sad message in it.
|
|
refused = call("pointer_click", {"id": session_id, "lease": lease})
|
|
assert refused["isError"] is True, refused
|
|
assert refused["structuredContent"]["exit_code"] == 9, refused
|
|
said = text_of(refused)
|
|
print(said.splitlines()[0])
|
|
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"})
|
|
assert refused["isError"] is True, refused
|
|
assert refused["structuredContent"]["exit_code"] == 3, refused
|
|
assert "session_list" in text_of(refused)
|
|
|
|
with subtest("an argument the schema refuses never reaches the broker"):
|
|
# No `lease`, so the server's own schema refuses before an argv list
|
|
# exists. The CLI is not run at all, which is the point.
|
|
refused = call("keyboard_type", {"id": session_id, "text": "x"})
|
|
assert refused["isError"] is True, refused
|
|
assert "lease" 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)
|
|
print(text_of(killed))
|
|
assert killed["structuredContent"]["ok"] is True, killed
|
|
live = [s["id"] for s in cli_json("list --json")["sessions"]]
|
|
assert session_id not in live, live
|
|
except Exception:
|
|
dump("session_kill over mcp", session_id)
|
|
raise
|
|
'';
|
|
}
|
|
)
|