Merge feat/mcp-server (9708154) into feat/mcp-auth
The base branch moved twelve commits while this work was in flight --
including the per-session live stream and its own contract bump -- so this
integrates rather than leaving a PR nobody can merge. Six files
conflicted; the interesting resolutions are the two that were not
textual.
**The contract is mcp-v3.1, not v2.1.** This branch bumped v2 -> v2.1 for
an additive change; `feat/mcp-server` bumped v2 -> v3 for the live stream,
also additive. Both point releases, both correct, and they cannot both be
the same document. So v3 stands as written and the HTTP transport is the
point release on top of it, by the same rule each of us applied
independently: v2 is still the only major bump, because it is still the
only one that removed anything.
**The counts are no longer literals.** This branch asserted `21 tools` and
`5 resources` in `checks/vm-mcp-http.nix` and `5` in `test_mcp_http.py`;
the stream added two tools and one fixed resource, so the surface is 23
and 6. Rather than re-hardcode numbers that will go stale again, the
check now counts against `--list-tools` and `--list-resources` -- the
server's own table -- and the unit test against `resources.FIXED`. That
is the lesson 9708154 ("count the unnarrowed resources against the
listing, not a literal") had already learned on the other side of this
merge, arrived at twice. A stale number here would have failed in a way
indistinguishable from the HTTP transport dropping tools, which is the
one thing those subtests exist to catch.
The rest were additive on both sides and both halves are kept: the TODO
table, the checks wiring, the README check rows, the architecture diagram
(their 23/10 counts with this branch's two-transport annotation).
`nix/module.nix` needed reconstructing -- git interleaved the bodies of
`hhstream-live` and `hhstream-mcp` because both units land between the
same surrounding lines -- so the live unit is taken verbatim and the MCP
unit placed after it, with this branch's options, tmpfiles entry,
firewall rule, two assertions and two warnings re-applied on top.
One thing deliberately NOT touched: the v3 change table cites `§6` for the
idle-clock exception, but the rule it means is `§8`. That is the other
branch's prose and its author's call, not something to quietly rewrite in
a merge.
Verified after resolution: 394 unit tests pass, and the module evaluates
with both units, the right ExecStart, one firewall port and both
warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KchcvnbfhhZhUHy83YL3Ya
This commit is contained in:
commit
f83717ba71
37 files changed
+4241
-101
No files matched your search
+3
-3
@@ -14,7 +14,7 @@
|
||||
# `buildPythonApplication` output is not.
|
||||
#
|
||||
# `grim` and `ffmpeg` do go on PATH, because the CLI itself spawns them --
|
||||
# `shot --output` and `record` are two of the twenty-one tools, and the server
|
||||
# `shot --output` and `record` are two of the twenty-three tools, and the server
|
||||
# is launched by an MCP client whose PATH is not ours to predict. `--prefix`
|
||||
# and not `--set`, so a deployment that wants its own ahead of these puts them
|
||||
# on PATH and wins.
|
||||
@@ -94,11 +94,11 @@ python3.pkgs.buildPythonApplication {
|
||||
echo "checking the wrapped entry point..."
|
||||
tools=$($out/bin/hhstream-mcp --list-tools)
|
||||
echo "$tools"
|
||||
test "$(echo "$tools" | wc -l)" -eq 21
|
||||
test "$(echo "$tools" | wc -l)" -eq 23
|
||||
|
||||
resources=$($out/bin/hhstream-mcp --list-resources)
|
||||
echo "$resources"
|
||||
test "$(echo "$resources" | wc -l)" -eq 8
|
||||
test "$(echo "$resources" | wc -l)" -eq 10
|
||||
|
||||
narrowed=$($out/bin/hhstream-mcp --list-tools --toolsets keyboard | wc -l)
|
||||
echo "--toolsets keyboard offers $narrowed tools"
|
||||
|
||||
+179
-14
@@ -46,6 +46,7 @@ let
|
||||
brokerRuntimeDir = "/run/${brokerRuntimeDirName}";
|
||||
controlSocket = "${brokerRuntimeDir}/control.sock";
|
||||
pointerSocket = "${brokerRuntimeDir}/pointer.sock";
|
||||
liveSocket = "${brokerRuntimeDir}/live.sock";
|
||||
|
||||
# Addresses that mean "this listener answers on loopback only". The spelling
|
||||
# `localhost` is included because it is what a person writes; it is not a
|
||||
@@ -164,6 +165,35 @@ let
|
||||
done
|
||||
exec ${lib.getExe' cfg.package "hhstream-server"} "$@"
|
||||
'';
|
||||
|
||||
# The same problem, for the stream daemon, one step worse.
|
||||
#
|
||||
# `grim` is an ordinary Wayland client: it needs XDG_RUNTIME_DIR *and* the
|
||||
# name of the socket the compositor actually bound, and that name is only
|
||||
# known once the compositor is up -- so, exactly as above, it cannot be an
|
||||
# `Environment=` line.
|
||||
#
|
||||
# MEASURED, in checks/vm-stream.nix, which is the check that exists to find
|
||||
# this: with the group but without the environment, the unit came up
|
||||
# `active (running)`, the broker attached, `stream status` said
|
||||
# `attached: true`, and every capture failed with
|
||||
#
|
||||
# grim: error: XDG_RUNTIME_DIR is invalid or not set in the environment.
|
||||
#
|
||||
# until the publisher gave up after ten in a row. A viewer with the right
|
||||
# phrase got a page and no frames, and nothing in the session's own state
|
||||
# said why -- the sibling failure to
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, and the reason this unit
|
||||
# spells out the whole capture command *and* hands it a session.
|
||||
execLive = pkgs.writeShellScript "hhstream-exec-live" ''
|
||||
for candidate in "$XDG_RUNTIME_DIR"/wayland-*; do
|
||||
if [ -S "$candidate" ]; then
|
||||
export WAYLAND_DISPLAY="''${candidate##*/}"
|
||||
break
|
||||
fi
|
||||
done
|
||||
exec ${lib.getExe' cfg.package "hhstream-live"} "$@"
|
||||
'';
|
||||
hyprlandConf = pkgs.writeText "hyprland.conf" (import ./hyprland-conf.nix {
|
||||
inherit lib;
|
||||
inherit (cfg) outputs extraConfig;
|
||||
@@ -701,15 +731,57 @@ in {
|
||||
|
||||
# The session-stream web app — `hhstream-live`, the router that serves a
|
||||
# live view of one session per phrase, over one port
|
||||
# (`docs/plans/2026-10-04-session-stream-webapp.md`).
|
||||
# (`docs/plans/2026-10-04-session-stream-webapp.md`, Stage 2 and 3).
|
||||
#
|
||||
# Only the *reach* of it is declared here so far: the port every stream
|
||||
# shares, the address it will bind, and whether that port is opened in
|
||||
# the firewall. The unit that runs the app, the phrases the broker keeps
|
||||
# in its records and the `session stream enable` verbs are later stages
|
||||
# of that plan — and deliberately so: a stream is switched on per
|
||||
# session, never for all of them, so nothing here turns one on.
|
||||
# `enable` runs the unit and hands the broker `/run/hhstream/live.sock`,
|
||||
# over which `hhstream session stream enable <id>` switches one stream
|
||||
# on. Everything else here is the *reach* of it: the port every stream
|
||||
# shares, the address it binds, and whether that port is opened in the
|
||||
# firewall.
|
||||
#
|
||||
# Running it still turns nothing on. A stream exists only for the
|
||||
# sessions it was enabled on — a stream is switched on per session, never
|
||||
# for all of them — so `enable = true` is a listener serving one form
|
||||
# until somebody asks for a session.
|
||||
stream = {
|
||||
enable = lib.mkOption {
|
||||
type = lib.types.bool;
|
||||
default = false;
|
||||
description = ''
|
||||
Run `hhstream-live`, the web app that publishes one session's
|
||||
screen at a URL whose path is a spoken phrase, and give the broker
|
||||
the socket it switches streams on over
|
||||
(`/run/hhstream/live.sock`).
|
||||
|
||||
Off by default, and running it turns **nothing** on: a stream
|
||||
exists only for the sessions `hhstream session stream enable` was
|
||||
called on, and until then this is a listener serving one form.
|
||||
That is deliberate — a live view of a desktop is readable by
|
||||
anyone who can reach the port and guess the phrase, so switching
|
||||
one on is a per-session act and never a consequence of the service
|
||||
being up.
|
||||
|
||||
Needs {option}`sessions.enable`: the phrase lives in the session
|
||||
record, and there are no sessions without the broker.
|
||||
'';
|
||||
};
|
||||
|
||||
fps = lib.mkOption {
|
||||
type = lib.types.ints.positive;
|
||||
default = 5;
|
||||
description = ''
|
||||
Frames a second a stream captures at when nobody says otherwise.
|
||||
|
||||
Five is one frame per ~200 ms plus a ~46 ms `grim`, measured rather
|
||||
than guessed; the daemon's own hard cap is 10, because this box is
|
||||
also running the compositor and the main frame publisher. Capture
|
||||
happens **only while somebody is connected**, so an enabled stream
|
||||
nobody is watching costs nothing at any rate.
|
||||
|
||||
`hhstream session stream enable --fps N` overrides it per stream.
|
||||
'';
|
||||
};
|
||||
|
||||
port = lib.mkOption {
|
||||
type = lib.types.port;
|
||||
default = 9988;
|
||||
@@ -1130,8 +1202,8 @@ in {
|
||||
environment.systemPackages =
|
||||
lib.mkIf (cfg.mcp.enable || cfg.mcp.http.enable) [ cfg.mcp.package ];
|
||||
|
||||
# A warning and not an assertion: eighteen of the twenty-one tools and six
|
||||
# of the eight resources need the broker, and an agent handed them against
|
||||
# A warning and not an assertion: twenty of the twenty-three tools and
|
||||
# seven of the ten resources need the broker, and an agent handed them against
|
||||
# a machine where it is off gets exit 5 from every one of them -- which is
|
||||
# a true answer, badly timed. The frame tools are genuinely useful on their
|
||||
# own, so this is a thing worth saying rather than a thing worth refusing.
|
||||
@@ -1489,6 +1561,97 @@ in {
|
||||
};
|
||||
};
|
||||
|
||||
# The stream daemon. A third executor beside the pointer driver, and the
|
||||
# split is the driver's: `grim` blocks tens to hundreds of milliseconds, so
|
||||
# the capture must not run where `touch` and `kill` are answered, and a
|
||||
# LAN-facing HTTP parser must not run in the frame server whose one-socket
|
||||
# contract cannot grow one (docs/CONTRACT-sessions.md §3.5).
|
||||
systemd.services.hhstream-live = lib.mkIf (cfg.sessions.enable && cfg.sessions.stream.enable) {
|
||||
description = "Per-session live stream for the headless Hyprland desktop";
|
||||
wantedBy = ["multi-user.target"];
|
||||
after = ["hyprland-headless.service"];
|
||||
# `BindsTo` for the pointer driver's reason: this process captures from
|
||||
# that compositor's outputs through `grim`, so when the compositor goes
|
||||
# it has nothing left to capture. The broker reports such a stream as
|
||||
# `attached: false` rather than pretending, and re-enabling re-attaches.
|
||||
bindsTo = ["hyprland-headless.service"];
|
||||
|
||||
environment = {
|
||||
PYTHONUNBUFFERED = "1";
|
||||
# The compositor's session, not this unit's own: `grim` has to find the
|
||||
# Wayland socket in here. `WAYLAND_DISPLAY` is set by `execLive` at
|
||||
# start, because the socket's name is only known once the compositor
|
||||
# has bound it. HOME is deliberately NOT redirected here the way the
|
||||
# frame server's is -- this unit runs as the operator's account, and
|
||||
# the compositor's runtime directory is not writable by it.
|
||||
XDG_RUNTIME_DIR = runtimeDir;
|
||||
};
|
||||
|
||||
serviceConfig = {
|
||||
Type = "simple";
|
||||
User = cfg.sessions.user;
|
||||
# The compositor's runtime directory is 0750 and owned by this group,
|
||||
# and `grim` is a Wayland client of it -- same reason the pointer
|
||||
# driver needs the group, one step further: this one has to *capture*,
|
||||
# not merely find the socket.
|
||||
SupplementaryGroups = [cfg.sessions.group];
|
||||
|
||||
# No `RuntimeDirectory`: /run/hhstream belongs to the broker's unit and
|
||||
# to the tmpfiles entry above, and a second RuntimeDirectory= on the
|
||||
# same path would delete the broker's control socket when this unit
|
||||
# stopped. The plan calls this out by name as the Stage 3 risk.
|
||||
WorkingDirectory = brokerRuntimeDir;
|
||||
UMask = "0007";
|
||||
|
||||
Restart = "on-failure";
|
||||
RestartSec = 1;
|
||||
NoNewPrivileges = true;
|
||||
KillMode = "process";
|
||||
|
||||
# `grim` is NOT on a unit's PATH, and the symptom of leaving it off is
|
||||
# a stream that serves an empty frame area without saying why --
|
||||
# docs/TODO/capture-binary-and-the-unit-path.md, found the first time
|
||||
# the capture ran as a unit rather than from a login shell. So the
|
||||
# whole capture command is spelled out here, with grim's store path.
|
||||
#
|
||||
# `--capture-command=<word>` and not `--capture-command <word>`:
|
||||
# MEASURED, as a unit crash-looping with
|
||||
#
|
||||
# hhstream-live serve: error: argument --capture-command: expected
|
||||
# one argument
|
||||
#
|
||||
# because grim's last word is a bare `-` (its "write to stdout"), and
|
||||
# argparse reads a lone dash as an option prefix rather than a value.
|
||||
# The `=` form is unambiguous for every word, so it is used for every
|
||||
# word rather than only the one that needs it.
|
||||
# Same second line of defence as the frame server's: `BindsTo=` stops
|
||||
# this unit when the compositor goes, but the compositor is only
|
||||
# *ready* once its socket is bound, and `execLive` has to find that
|
||||
# socket to export its name.
|
||||
ExecStartPre = "${findSession} >/dev/null";
|
||||
|
||||
ExecStart = lib.escapeShellArgs (
|
||||
[
|
||||
execLive
|
||||
"serve"
|
||||
"--control-socket=${liveSocket}"
|
||||
"--bind=${cfg.sessions.stream.bind}"
|
||||
"--port=${toString cfg.sessions.stream.port}"
|
||||
"--fps=${toString cfg.sessions.stream.fps}"
|
||||
]
|
||||
++ map (word: "--capture-command=${word}") [
|
||||
(lib.getExe pkgs.grim)
|
||||
"-c" # include the cursor
|
||||
"-t"
|
||||
"jpeg"
|
||||
"-q"
|
||||
"80"
|
||||
"-" # write to stdout
|
||||
]
|
||||
);
|
||||
};
|
||||
};
|
||||
|
||||
# ── the MCP server, over HTTP ──────────────────────────────────────
|
||||
#
|
||||
# The fourth unit, and the first one that listens on a port rather than a
|
||||
@@ -1508,11 +1671,13 @@ in {
|
||||
description = "MCP server for the headless Hyprland desktop (HTTP)";
|
||||
wantedBy = ["multi-user.target"];
|
||||
after = ["hyprland-headless.service" "hhstream-sessions.service"];
|
||||
# `After` and `Wants`, not `BindsTo`: three of the twenty-one tools and
|
||||
# two of the five resources are frame-socket verbs that answer with the
|
||||
# broker down, and the rest answer exit 5, which is a true answer. A
|
||||
# listener that vanished with the broker would turn that into a
|
||||
# connection refused, which tells a client nothing.
|
||||
# `After` and `Wants`, not `BindsTo`: the frame-socket verbs (`shot`,
|
||||
# `record`, `run`, and the `status` and `screen` resources) answer with
|
||||
# the broker down, and everything else answers exit 5, which is a true
|
||||
# answer. A listener that vanished with the broker would turn that into a
|
||||
# connection refused, which tells a client nothing. Deliberately no
|
||||
# counts here -- the surface grows, and a comment with a number in it
|
||||
# goes stale without anything failing.
|
||||
wants = ["hhstream-sessions.service"];
|
||||
|
||||
environment = {
|
||||
|
||||
@@ -38,6 +38,13 @@ python3.pkgs.buildPythonApplication {
|
||||
# The web app: importing the server pulls in the router, the publisher and
|
||||
# the pages.
|
||||
"hhstream_live.server"
|
||||
# The two halves of `live.sock` (CONTRACT-sessions.md §3.5). Both are
|
||||
# stdlib-only, and they are named here because they are the one pair in
|
||||
# this package that has to agree with each other across two processes --
|
||||
# so an import error in either is worth finding at build time rather than
|
||||
# the first time an operator enables a stream.
|
||||
"hhstream_live.control"
|
||||
"hhstreamd.live"
|
||||
];
|
||||
|
||||
# `pythonImportsCheck` only *imports*, and `hhstream_live.phrase` reads its
|
||||
|
||||
Reference in new issue
Block a user