test(mcp): the argv each tool builds, the mapping, and the server in a guest

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
This commit is contained in:
HermenixandClaude Opus 5 committed 2026-10-11 06:32:55 +00:00
1 parent 549c73e8ae
commit fea55eecde
8 files changed
+1984 -3

No files matched your search

+8 -1
View File
@@ -1,6 +1,7 @@
# The flake's `checks` output. One file per check; this is only the wiring.
#
# unit -- pytest over tests/, against the nix/package.nix build
# vm-mcp -- the MCP server over stdio, against a live broker
# vm-basic -- nixosTest with a fake capture backend: module + wire contract
# vm-hyprland -- nixosTest with the real compositor and grim
# vm-sessions -- nixosTest with the real compositor and the session broker
@@ -32,6 +33,7 @@
}:
let
hhstream = self.packages.${system}.hhstream;
hhstream-mcp = self.packages.${system}.hhstream-mcp;
hhsModule = self.nixosModules.default;
testTools = pkgs.callPackage ./lib/test-tools.nix { };
# The session checks take the same arguments; naming them once keeps a new
@@ -42,7 +44,7 @@ let
};
in
{
unit = pkgs.callPackage ./unit.nix { inherit hhstream; };
unit = pkgs.callPackage ./unit.nix { inherit hhstream hhstream-mcp; };
vm-basic = pkgs.callPackage ./vm-basic.nix {
inherit hhstream hhsModule testTools;
@@ -73,4 +75,9 @@ in
vm-stream-firewall = pkgs.callPackage ./vm-stream-firewall.nix {
inherit hhstream hhsModule testTools;
};
# The session machine again, plus `mcp.enable`, driven over stdio by a
# JSON-RPC client the check writes itself. `sessionArgs` plus the one package
# the others have no reason to carry.
vm-mcp = pkgs.callPackage ./vm-mcp.nix (sessionArgs // { inherit hhstream-mcp; });
}
+175
View File
@@ -0,0 +1,175 @@
#!/usr/bin/env python3
"""``hhs-mcp-call`` -- drive an MCP server over stdio from a shell.
What `checks/vm-mcp.nix` uses to talk to `hhstream-mcp` in the guest, and
deliberately **not** the MCP SDK's own client: the SDK on both ends would agree
with itself about a framing neither side had to get right. This is raw
JSON-RPC, newline-delimited, written against the specification -- the same
choice, and for the same reason, as `tests/assert_stream.py` being a second
implementation of the frame contract.
One server process per invocation, which means every call re-does the
`initialize` handshake. That is a feature here: the handshake is one of the
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 session_touch '{"id": "s-1"}' one call, arguments as JSON
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
not JSON-RPC -- which is the one outcome no assertion should be able to mistake
for a reply.
"""
from __future__ import annotations
import argparse
import json
import signal
import subprocess
import sys
from typing import Any
#: The protocol version this client speaks. Named rather than negotiated: a
#: server that answers a different one is a thing the test should see.
PROTOCOL_VERSION = "2025-06-18"
def fail(message: str) -> None:
print(f"hhs-mcp-call: {message}", file=sys.stderr)
raise SystemExit(2)
class Server:
"""One ``hhstream-mcp`` process, spoken to over its stdin and stdout."""
def __init__(self, command: list[str], timeout: int) -> None:
self.timeout = timeout
# stderr is left alone on purpose: the server logs there, and in a
# nixosTest that ends up in the build log beside the assertion that
# failed, which is where it is wanted.
self.process = subprocess.Popen(
command,
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
text=True,
bufsize=1,
)
self.next_id = 0
def send(self, message: dict[str, Any]) -> None:
assert self.process.stdin is not None
self.process.stdin.write(json.dumps(message) + "\n")
self.process.stdin.flush()
def read(self) -> dict[str, Any]:
assert self.process.stdout is not None
# An alarm rather than a poll loop: a server that never answers must
# fail the check, not hang the test driver until its global timeout.
signal.alarm(self.timeout)
try:
line = self.process.stdout.readline()
except KeyboardInterrupt: # pragma: no cover -- the alarm handler
fail(f"no answer within {self.timeout}s")
raise
finally:
signal.alarm(0)
if not line:
fail(f"the server closed its stream (exit {self.process.poll()})")
try:
return json.loads(line)
except json.JSONDecodeError:
# The failure a stray `print` on stdout produces, named as such:
# the tools run the CLI in process, and this is what it looks like
# when something it printed reached the transport.
fail(f"not JSON-RPC on the server's stdout: {line!r}")
raise AssertionError("unreachable")
def request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
self.next_id += 1
wanted = self.next_id
self.send(
{"jsonrpc": "2.0", "id": wanted, "method": method, "params": params or {}}
)
answer = self.read()
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']}")
return answer["result"]
def initialize(self) -> dict[str, Any]:
result = self.request(
"initialize",
{
"protocolVersion": PROTOCOL_VERSION,
"capabilities": {},
"clientInfo": {"name": "hhs-mcp-call", "version": "0"},
},
)
self.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
return result
def close(self) -> int:
assert self.process.stdin is not None
self.process.stdin.close()
try:
return self.process.wait(timeout=self.timeout)
except subprocess.TimeoutExpired: # pragma: no cover
self.process.kill()
return -1
def _alarm(signum, frame): # pragma: no cover -- raises into read()
raise KeyboardInterrupt
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(prog="hhs-mcp-call", description=__doc__)
parser.add_argument(
"--server",
default="hhstream-mcp",
help="the MCP server to spawn (default: %(default)s, from PATH)",
)
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("tool", nargs="?", help="the tool to call")
parser.add_argument("arguments", nargs="?", default="{}", help="its arguments, as JSON")
args = parser.parse_args(argv)
signal.signal(signal.SIGALRM, _alarm)
try:
arguments = json.loads(args.arguments)
except json.JSONDecodeError as exc:
fail(f"arguments are not JSON: {exc}")
return 2
if not isinstance(arguments, dict):
fail("arguments must be a JSON object")
server = Server([args.server], args.timeout)
try:
handshake = server.initialize()
if args.initialize:
print(json.dumps(handshake, indent=2, sort_keys=True))
return 0
if args.list:
print(json.dumps(server.request("tools/list"), indent=2, sort_keys=True))
return 0
if not args.tool:
fail("name a tool, or pass --list or --initialize")
result = server.request(
"tools/call", {"name": args.tool, "arguments": arguments}
)
print(json.dumps(result, indent=2, sort_keys=True))
return 0
finally:
server.close()
if __name__ == "__main__":
raise SystemExit(main())
+20 -2
View File
@@ -16,6 +16,7 @@
runCommand,
python3,
hhstream,
hhstream-mcp,
}:
let
# `xkbcommon` beside `pywayland`, and it is not optional: `tests/pointer/
@@ -24,7 +25,19 @@ let
# needs a level-three mask rather than Shift. A suite that could skip those
# would let the unmappable-character path rot, which is the path that decides
# whether a bad string types a prefix.
pytestEnv = python3.withPackages (ps: [ ps.pytest ps.pywayland ps.xkbcommon ]);
#
# `mcp` beside them, for `tests/unit/test_mcp_server.py`. That file imports
# the SDK on purpose and is not allowed to skip: the tool table itself is
# stdlib-only and tested without it, but the step that turns the table into
# `mcp.types.Tool` objects is where a malformed schema or a name the spec
# refuses would show up, and a file that skipped when the SDK was absent
# would be green in exactly the build where that mattered.
pytestEnv = python3.withPackages (ps: [
ps.pytest
ps.pywayland
ps.xkbcommon
ps.mcp
]);
# Only the suite itself, so an editor's droppings or a local .pytest_cache
# cannot change the derivation's hash.
@@ -61,11 +74,16 @@ runCommand "hhstream-unit"
# point PYTHONPATH at what nix/package.nix installed. Importing it here rather
# than letting pytest do it makes a packaging problem distinguishable from a
# test failure.
export PYTHONPATH=${hhstream}/${python3.sitePackages}
export PYTHONPATH=${hhstream}/${python3.sitePackages}:${hhstream-mcp}/${python3.sitePackages}
export PYTHONDONTWRITEBYTECODE=1
export HOME=$PWD
python3 -c 'import hhstream; print("testing hhstream", hhstream.__version__, "from", hhstream.__file__)'
python3 -c 'import hhstreamd.ipc, hhstream_pointer; print("broker ipc client + pointer driver import")'
# The second distribution, on the path beside the first. `tests/unit`'s
# conftest adds `../src` to sys.path, which does not exist in this sandbox --
# so here, as for `hhstream`, the import comes from what Nix installed, and a
# packaging mistake is distinguishable from a test failure.
python3 -c 'import hhstream_mcp.tools as t; print("mcp tool table:", len(t.TOOLS), "tools")'
set +e
pytest suite \
+375
View File
@@ -0,0 +1,375 @@
# 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
'';
}
)
+152
View File
@@ -0,0 +1,152 @@
"""A recording stand-in for the CLI, and two image fixtures, for the MCP tests.
The MCP server calls ``hhstream.cli``'s handlers in this process, so what sits
between a tool and the broker is **the argv list** -- and that list is the only
thing this layer decides. :class:`FakeCli` is therefore an entry point that
records the argv it was given, prints whatever the test told it to, and returns
the exit code the test chose: everything the real entry point is, minus the
broker.
That is also why there is no live socket anywhere in this suite. The broker's
behaviour is `tests/sessions`' subject and the VM checks'; what is left here is
the shim. Two tests in ``test_mcp_invoke.py`` do drive the **real** entry point
against a socket path that does not exist, which is the honest way to prove the
dispatch, the capture and the exit-code mapping without standing a daemon up.
"""
from __future__ import annotations
import json
import pathlib
import struct
import sys
import zlib
from typing import Any
class FakeCli:
"""Where :func:`hhstream_mcp.invoke.dispatch` goes in a test.
Prints through ``sys.stdout``/``sys.stderr`` rather than returning text, so
the capture under test is exercised rather than bypassed.
"""
def __init__(
self,
*,
stdout: str = "",
stderr: str = "",
exit_code: int = 0,
write_png: bytes | None = None,
raises: BaseException | None = None,
) -> None:
self.stdout = stdout
self.stderr = stderr
self.exit_code = exit_code
self.write_png = write_png
self.raises = raises
#: Every argv this was called with, in order.
self.calls: list[list[str]] = []
def __call__(self, argv: list[str]) -> int:
self.calls.append(list(argv))
if self.write_png is not None:
destination = _value_of("--out", argv)
if destination:
pathlib.Path(destination).write_bytes(self.write_png)
if self.stdout:
sys.stdout.write(self.stdout)
if self.stderr:
sys.stderr.write(self.stderr)
if self.raises is not None:
raise self.raises
return self.exit_code
@property
def argv(self) -> list[str]:
"""The single call's argv. Fails loudly if there was not exactly one."""
assert len(self.calls) == 1, f"expected one CLI call, got {self.calls}"
return self.calls[0]
def _value_of(name: str, argv: list[str]) -> str | None:
prefix = f"{name}="
for argument in argv:
if argument.startswith(prefix):
return argument[len(prefix) :]
return None
def reply(**fields: Any) -> str:
"""A protocol object the way the CLI prints one: ``json.dumps(indent=2)``."""
return json.dumps(fields, indent=2, sort_keys=True) + "\n"
def png(width: int = 8, height: int = 4) -> bytes:
"""A minimal valid truecolour PNG of a known size.
Built here rather than shared with the suite's other helper because what is
under test is "the server reports the geometry the file actually has", so
the size has to be the test's to choose.
"""
def chunk(kind: bytes, data: bytes) -> bytes:
return (
struct.pack(">I", len(data))
+ kind
+ data
+ struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
)
raster = (b"\x00" + b"\x10\x20\x30" * width) * height
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+ chunk(b"IDAT", zlib.compress(raster, 9))
+ chunk(b"IEND", b"")
)
def jpeg(width: int = 6, height: int = 3) -> bytes:
"""Enough of a JPEG to carry a SOF0: magic, APP0, SOF0, EOI.
Not a decodable image, deliberately: what is under test is the header scan
that has to skip a segment it does not care about and find the one it does.
"""
app0 = (
b"\xff\xe0"
+ struct.pack(">H", 16)
+ b"JFIF\x00"
+ b"\x01\x01\x00"
+ b"\x00\x01" * 2
+ b"\x00\x00"
)
sof0 = (
b"\xff\xc0"
+ struct.pack(">H", 11)
+ b"\x08"
+ struct.pack(">HH", height, width)
+ b"\x01\x01\x11\x00"
)
return b"\xff\xd8" + app0 + sof0 + b"\xff\xd9"
def isolate(monkeypatch, tmp_path: pathlib.Path) -> None:
"""Point every path the CLI reads from the environment at ``tmp_path``.
A developer's shell has `$HHSTREAM_SOCKET` set, and the real entry point
reads it -- so without this a test could reach a live broker on the machine
it is running on. The lease directory is redirected for the same reason:
`pointer acquire` writes a cache there, and a test must not touch the one a
real session is using.
"""
monkeypatch.setenv("HHSTREAM_SOCKET", str(tmp_path / "control.sock"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "stream.sock"))
monkeypatch.setenv("HHSTREAM_LEASE_DIR", str(tmp_path / "leases"))
# `$HHSTREAM_LEASE` outranks the cache in `hhstream_session.lease.recall`,
# so an inherited one would hand a gesture a lease it never acquired.
monkeypatch.delenv("HHSTREAM_LEASE", raising=False)
+389
View File
@@ -0,0 +1,389 @@
"""The runner: how the CLI is called in process, decoded, and mapped to a code.
Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because
the subject is what this layer decides -- the argv list and the mapping. Three
tests drive the **real** entry point, against a control socket that does not
exist: that is the honest way to prove the dispatch, the capture and the
exit-code mapping against the CLI's actual parser without standing a daemon up.
"""
from __future__ import annotations
import contextlib
import os
import signal
import mcp_fake
import pytest
from hhstreamd.protocol import ExitCode
from hhstream_mcp import invoke, media
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
# ── the call ───────────────────────────────────────────────────────────────
def test_the_argv_reaches_the_entry_point_unchanged():
fake = mcp_fake.FakeCli(stdout="hello\n")
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.ok
assert outcome.stdout == "hello\n"
assert fake.argv == ["session", "list", "--json"]
assert outcome.argv == ["session", "list", "--json"]
def test_a_metacharacter_is_one_argument_and_never_a_statement():
"""There is no shell between a tool and the CLI, and no string either."""
fake = mcp_fake.FakeCli()
nasty = "; rm -rf / #"
invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty])
assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty]
def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys):
"""A print on stdout here would be a parse error at the client."""
fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n")
outcome = invoke.Runner(fake).run(["status"])
assert outcome.stdout == "on stdout\n"
assert outcome.stderr == "on stderr\n"
escaped = capsys.readouterr()
assert escaped.out == ""
assert escaped.err == ""
def test_sys_exit_is_the_exit_code_a_process_would_have_had():
"""argparse refuses with `sys.exit(2)`; handlers exit on a missing tool."""
fake = mcp_fake.FakeCli(raises=SystemExit(2))
assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE)
# `sys.exit("message")` is status 1 in a real process, and the message is
# the exit code object rather than something printed.
fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH"))
assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE
fake = mcp_fake.FakeCli(raises=SystemExit(None))
assert invoke.Runner(fake).run(["status"]).returncode == 0
def test_an_uncaught_exception_becomes_exit_one_with_its_traceback():
"""What a CLI process would have done, rather than a transport error."""
fake = mcp_fake.FakeCli(raises=RuntimeError("boom"))
outcome = invoke.Runner(fake).run(["session", "list", "--json"])
assert outcome.returncode == invoke.GENERIC_FAILURE
assert "RuntimeError: boom" in outcome.stderr
assert "Traceback" in outcome.stderr
def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result():
"""BaseException is caught on purpose; the code still says "failed"."""
fake = mcp_fake.FakeCli(raises=KeyboardInterrupt())
outcome = invoke.Runner(fake).run(["session", "list"])
assert outcome.returncode == invoke.GENERIC_FAILURE
def test_a_call_runs_with_the_serialising_lock_held():
"""The CLI prints to a process-global stdout, so one call at a time.
Asserted from inside the call rather than by racing two threads and hoping
their output interleaves: a race that passes by luck is not a test. The
private name is the point -- what is being asserted is that this specific
lock is held while a handler runs.
"""
def probing(argv):
free = invoke._ONE_AT_A_TIME.acquire(blocking=False)
if free:
invoke._ONE_AT_A_TIME.release()
print("free" if free else "held", end="")
return 0
assert invoke.Runner(probing).run(["status"]).stdout == "held"
# ── decoding ───────────────────────────────────────────────────────────────
def test_the_protocol_object_is_read_from_stdout_on_success():
fields = {"ok": True, "id": "s-1", "session": {"state": "running"}}
fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields))
assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields
def test_the_protocol_object_is_read_from_stderr_on_failure():
"""The CLI's own split: an error goes to stderr whatever the output mode."""
fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
fake = mcp_fake.FakeCli(
stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE)
)
outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"])
assert not outcome.ok
assert outcome.payload() == fields
def test_an_object_printed_under_a_bare_line_is_still_found():
"""`session start` prints the id beside its object; parsing must survive it."""
fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n')
assert invoke.Runner(fake).run(["session", "start"]).payload() == {
"ok": True,
"id": "s-1",
}
def test_no_json_at_all_is_none_rather_than_an_invention():
fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n")
assert invoke.Runner(fake).run(["status"]).payload() is None
def test_a_json_array_is_not_mistaken_for_the_protocol_object():
assert invoke.first_json_object("[1, 2, 3]") is None
assert invoke.first_json_object('[{"a": 1}]') == {"a": 1}
# ── the real entry point, with nothing listening ───────────────────────────
def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code():
"""argparse's own refusal, through the CLI's own parser, mapped to exit 2."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.USAGE)
assert "invalid choice" in outcome.stderr
# And nothing escaped onto the real stdout: argparse prints usage there for
# --help and to stderr for an error, and both are captured.
assert outcome.stdout == ""
def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code():
"""No socket, no daemon, no fake: the mapping end to end."""
outcome = invoke.Runner().run(["session", "list", "--json"])
assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE)
payload = outcome.payload()
assert payload is not None
assert payload["error"] == "daemon_unreachable"
def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker():
"""Exit 9 is produced by the CLI before the socket is touched at all."""
outcome = invoke.Runner().run(
["session", "pointer", "click", "--json", "--", "s-1"]
)
assert outcome.returncode == int(ExitCode.NO_LEASE)
assert (outcome.payload() or {}).get("error") == "no_lease"
def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces():
"""The one capability lost by calling the CLI in process, said out loud."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "cannot read" in outcome.stderr
assert "sg hhstream" in outcome.stderr
def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch):
readable = tmp_path / "stream.sock"
readable.write_bytes(b"")
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable))
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"])
assert "sg hhstream" not in outcome.stderr
def test_a_session_verb_never_earns_the_frame_socket_hint():
"""It has nothing to do with the control socket, so it must not be offered."""
outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run(
["session", "pointer", "acquire", "--json", "--", "s-1"]
)
assert "sg hhstream" not in outcome.stderr
# ── the exit-code table ────────────────────────────────────────────────────
@pytest.mark.parametrize(
"code",
[
ExitCode.USAGE,
ExitCode.NO_SUCH_SESSION,
ExitCode.BAD_STATE,
ExitCode.DAEMON_UNREACHABLE,
ExitCode.POLICY,
ExitCode.TIMEOUT,
ExitCode.BUSY,
ExitCode.NO_LEASE,
ExitCode.COMPOSITOR,
],
)
def test_every_frozen_exit_code_has_a_remedy_naming_itself(code):
"""A new code in the frozen table must not fall through to a generic line."""
text = invoke.remedy_for(int(code))
assert text.startswith(f"exit {int(code)} ({code.name})")
assert int(code) in invoke.REMEDY
def test_the_lease_codes_say_the_two_different_things_an_agent_must_do():
"""8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4)."""
busy = invoke.remedy_for(int(ExitCode.BUSY))
none_held = invoke.remedy_for(int(ExitCode.NO_LEASE))
assert "pointer_state" in busy and "wait" in busy
assert "pointer_acquire" in none_held
# "acquire one" must not be the advice for BUSY: that is the one confusion
# the two codes exist to prevent.
assert "pointer_acquire" not in busy
def test_an_unclassified_code_is_still_a_failure_and_says_so():
text = invoke.remedy_for(42)
assert "exit 42 (UNCLASSIFIED)" in text
assert "do not assume anything happened" in text
def test_generic_failure_is_its_own_case():
"""Exit 1 is the frame verbs', and is not in the broker's frozen table."""
assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode]
assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE)
# ── launch, for `run` ──────────────────────────────────────────────────────
def test_launch_leaves_the_application_running_in_its_own_session(wayland):
"""`run` launches and forgets, and a killed server must not take it along."""
spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3)
try:
assert not spawned.exited
assert spawned.pid > 0
os.kill(spawned.pid, 0)
# Its own session, so a client that kills this server's process group
# does not kill the desktop with it.
assert os.getsid(spawned.pid) == spawned.pid
assert os.getsid(spawned.pid) != os.getsid(0)
finally:
with contextlib.suppress(ProcessLookupError):
os.kill(spawned.pid, signal.SIGTERM)
def test_launch_reports_an_application_that_died_inside_the_window(wayland):
spawned = invoke.Runner().launch(["false"], settle=5.0)
assert spawned.exited
assert spawned.pid > 0
def test_launch_hands_back_what_a_failing_application_said(wayland):
spawned = invoke.Runner().launch(
["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0
)
assert spawned.exited
assert "cannot open display" in spawned.stderr
def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland):
spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0)
assert spawned.exited
assert spawned.pid == 0
assert "no executable" in spawned.stderr
def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch):
"""`env_for_session` exits with the message; it is handed on verbatim."""
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock"))
(tmp_path / "empty").mkdir()
spawned = invoke.Runner().launch(["true"], settle=1.0)
assert spawned.exited
assert spawned.pid == 0
assert "no wayland socket" in spawned.stderr
assert "is the compositor up?" in spawned.stderr
@pytest.fixture
def wayland(workdir, monkeypatch):
"""A runtime directory with something `env_for_session` accepts in it.
A real AF_UNIX socket, because that function checks `is_socket()` -- an
empty file would make it refuse for a reason these tests are not about.
The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX
address is capped near 108 bytes and pytest's own paths are longer than
that.
"""
import socket
listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
listener.bind(str(workdir / "wayland-0"))
monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock"))
yield workdir
listener.close()
# ── artefact readers ───────────────────────────────────────────────────────
def test_a_png_is_sniffed_by_its_header_not_its_extension():
image = media.sniff(mcp_fake.png(width=13, height=7))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/png", 13, 7)
def test_a_jpeg_under_a_png_filename_is_still_a_jpeg():
"""The publisher serves `image/jpeg` on the deployment machine."""
image = media.sniff(mcp_fake.jpeg(width=6, height=3))
assert image is not None
assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3)
def test_an_unrecognised_format_is_none_rather_than_a_guess():
assert media.sniff(b"GIF89a\x00\x00") is None
assert media.sniff(b"") is None
def test_the_measured_record_rate_is_read_off_the_cli_s_own_line():
found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n")
assert found is not None
assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9)
def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed():
assert media.recording("/tmp/out.mp4\n") is None
assert media.recording("") is None
def test_temp_name_is_unique_per_process_and_under_a_named_directory():
first = invoke.temp_name("recording", ".mp4")
assert "hhstream-mcp" in first
assert first.endswith(".mp4")
assert str(os.getpid()) in first
+312
View File
@@ -0,0 +1,312 @@
"""The SDK wiring: the handshake, the listing, and one call of each shape.
This is the file that imports the MCP SDK, and it does so unconditionally. The
tool table is standard library and tested without it
(``test_mcp_tools.py``); what is left is the part only the SDK can judge --
whether every schema validates, whether every name is one the specification
allows, and whether a refusal arrives as a tool error rather than a success. A
file that skipped when the SDK was absent would be green in exactly the build
where that mattered, which is why ``checks/unit.nix`` puts ``mcp`` in the test
environment rather than making it optional.
The server runs in process, over the SDK's in-memory transport. The stdio
transport itself is proved end to end by ``checks/vm-mcp.nix`` and by the
handshake in the pull request description -- a pair of memory streams cannot
tell you that a stray ``print`` has corrupted stdout.
"""
from __future__ import annotations
import json
import os
import anyio
import jsonschema
import mcp.types as types
import mcp_fake
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 hhstream_mcp import SERVER_NAME, __version__, invoke, server, tools
@pytest.fixture(autouse=True)
def _isolated(monkeypatch, tmp_path):
mcp_fake.isolate(monkeypatch, tmp_path)
@pytest.fixture
def session():
"""`session(...)` -> (the recording CLI, a connected client session).
The stand-in is scripted per test, exactly as in the table's own tests;
what is added here is a real client on the other end of a real server, so
`initialize` and the two request types are exercised rather than asserted
about.
"""
def _session(**script):
fake = mcp_fake.FakeCli(**script)
built = server.build(invoke.Runner(fake))
return fake, create_connected_server_and_client_session(
built, raise_exceptions=True
)
return _session
def run(coroutine):
return anyio.run(coroutine)
# ── the handshake ──────────────────────────────────────────────────────────
def test_initialize_names_this_server_and_declares_tools(session):
_, connected = session()
async def go():
async with connected as client:
result = await client.initialize()
return result
initialized = run(go)
assert initialized.serverInfo.name == SERVER_NAME
assert initialized.serverInfo.version == __version__
assert initialized.capabilities.tools 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
assert "`session_touch` is the ONLY" in initialized.instructions
def test_the_instructions_carry_both_rules():
assert "`session_touch` is the ONLY" in server.INSTRUCTIONS
assert "POINTER lease" in server.INSTRUCTIONS
assert "There is no keyboard lease" in server.INSTRUCTIONS
# And the two lease codes an agent has to tell apart.
assert "Exit 8 means" in server.INSTRUCTIONS
assert "9 means you need to acquire one" in server.INSTRUCTIONS
# ── the listing ────────────────────────────────────────────────────────────
def test_tools_list_returns_every_tool_with_a_title_and_a_description(session):
_, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.list_tools()
listed = run(go).tools
assert {tool.name for tool in listed} == set(tools.BY_NAME)
for tool in listed:
assert tool.title, tool.name
assert tool.description and len(tool.description) > 40, tool.name
assert tool.annotations is not None
assert tool.annotations.openWorldHint is False
def test_every_tool_name_is_one_the_specification_allows():
for tool in tools.TOOLS:
result = validate_tool_name(tool.name)
assert result.is_valid, (tool.name, result.warnings)
# Warnings are not failures to the SDK, but a name that earns one is a
# name that will be mangled by some client.
assert result.warnings == [], (tool.name, result.warnings)
def test_every_input_schema_is_a_schema_the_validator_accepts():
"""The SDK validates every call against these; a bad one fails at call time."""
for tool in tools.TOOLS:
jsonschema.Draft202012Validator.check_schema(tool.schema)
def test_the_read_only_hint_is_set_from_the_verb_and_not_from_the_name():
for tool in tools.TOOLS:
described = server.describe(tool)
assert described.annotations.readOnlyHint == tool.read_only
if tool.read_only:
assert described.annotations.destructiveHint is None
else:
assert described.annotations.destructiveHint is tool.destructive
# ── the schemas, through the validator the server actually uses ────────────
def test_move_requires_exactly_one_of_to_and_by():
schema = tools.BY_NAME["pointer_move"].schema
jsonschema.validate({"id": "s", "lease": "L", "to": [0.5, 0.5]}, schema)
jsonschema.validate({"id": "s", "lease": "L", "by": [0.5, 0.5]}, schema)
for bad in (
{"id": "s", "lease": "L"},
{"id": "s", "lease": "L", "to": [0.5, 0.5], "by": [0.1, 0.1]},
{"id": "s", "lease": "L", "to": [0.5]},
{"id": "s", "lease": "L", "to": [0.5, 0.5, 0.5]},
):
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate(bad, schema)
def test_home_and_ephemeral_home_are_refused_together_by_the_schema():
"""The CLI's mutually exclusive group, moved forward to where it is cheaper."""
schema = tools.BY_NAME["session_start"].schema
jsonschema.validate({"app": "foot"}, schema)
jsonschema.validate({"app": "foot", "home": "/tmp/h"}, schema)
jsonschema.validate({"app": "foot", "ephemeral_home": True}, schema)
with pytest.raises(jsonschema.ValidationError):
jsonschema.validate({"app": "foot", "home": "/tmp/h", "ephemeral_home": True}, schema)
def test_a_gesture_without_a_lease_is_refused_before_the_cli_is_run(session):
"""The lease is required, so the schema refuses and no argv is built."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("pointer_click", {"id": "s-1"})
result = run(go)
assert result.isError
assert "lease" in result.content[0].text
# The point of a schema refusal: the CLI was never reached.
assert fake.calls == []
# ── calls ──────────────────────────────────────────────────────────────────
def test_a_successful_call_carries_the_protocol_object_as_structured_content(session):
reply = {"ok": True, "sessions": []}
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", {})
result = run(go)
assert not result.isError
assert result.structuredContent == reply
assert fake.calls == [["session", "list", "--json"]]
def test_a_refused_call_arrives_as_a_tool_error_an_agent_can_read(session):
reply = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"}
_, connected = session(
stderr=json.dumps(reply, indent=2), exit_code=int(ExitCode.NO_LEASE)
)
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool(
"pointer_click", {"id": "s-1", "lease": "stale"}
)
result = run(go)
assert result.isError is True
assert result.structuredContent["exit_code"] == int(ExitCode.NO_LEASE)
text = result.content[0].text
assert "exit 9 (NO_LEASE)" in text
assert "pointer_acquire" in text
def test_a_frame_arrives_as_image_content_beside_its_geometry(session):
frame = mcp_fake.png(width=64, height=48)
_, connected = session(write_png=frame, stdout="/tmp/ignored.png\n")
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("shot", {})
result = run(go)
assert not result.isError
kinds = [block.type for block in result.content]
assert kinds == ["text", "image"]
text, image = result.content
assert "64x48 image/png" in text.text
assert image.mimeType == "image/png"
import base64
assert base64.b64decode(image.data) == frame
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."""
fake, connected = session()
async def go():
async with connected as client:
await client.initialize()
return await client.call_tool("session_detonate", {})
result = run(go)
assert result.isError is True
assert "no such tool: 'session_detonate'" in result.content[0].text
assert "session_touch" in result.content[0].text
assert fake.calls == []
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", {})
assert result.isError is True
assert result.structuredContent["exit_code"] == invoke.GENERIC_FAILURE
assert "the broker said something odd" in result.content[0].text
def test_the_transport_is_moved_off_the_descriptor_the_cli_prints_to():
"""The one thing an in-process CLI call could break, asserted directly."""
read_fd, write_fd = os.pipe()
saved_out, saved_err = os.dup(1), os.dup(2)
log_read, log_write = os.pipe()
try:
os.dup2(write_fd, 1)
os.dup2(log_write, 2)
_, stdout = server.claim_transport()
# After claiming, this process's own stdout is the log (fd 2), not the
# stream the client reads.
assert os.path.sameopenfile(1, 2)
assert not os.path.sameopenfile(1, stdout.wrapped.fileno())
# ...and stdin cannot eat a request.
assert os.readlink(f"/proc/self/fd/0") == os.devnull
finally:
os.dup2(saved_out, 1)
os.dup2(saved_err, 2)
for fd in (saved_out, saved_err, read_fd, write_fd, log_read, log_write):
try:
os.close(fd)
except OSError:
pass
def test_the_listing_is_what_the_entry_point_prints(capsys):
"""`--list-tools` is the package's own install check; keep it honest."""
assert server.main(["--list-tools"]) == 0
printed = capsys.readouterr().out.splitlines()
assert len(printed) == len(tools.TOOLS)
assert printed[0].split("\t")[0] == tools.TOOLS[0].name
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"]
assert isinstance(blocks[0], types.TextContent)
+553
View File
@@ -0,0 +1,553 @@
"""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()