examples: agent-eyes subcommand helper (status/shot/run/record)

One front door to the headless session, for reuse by any consumer: it
discovers whichever wayland-N socket exists, re-execs itself under
sg hhstream when the login predates the group membership, and encodes
recordings at the measured frame rate so clips play at true speed.
This commit is contained in:
Hermenix committed 2026-10-01 03:18:31 +00:00
1 parent 2b32153c8b
commit 09903c5676
2 files changed
+191

No files matched your search

+27
View File
@@ -1,5 +1,32 @@
# examples
## `agent-eyes` — the short commands
The everyday front door to the session: one subcommand each, no environment
juggling, and it re-execs itself under `sg hhstream` when the login predates the
group membership.
```bash
examples/agent-eyes status # services, socket, group access, liveness probe
examples/agent-eyes shot --out /tmp/s.jpg # one frame of the screen
examples/agent-eyes run -- chromium ... # launch a GUI app INTO the session
examples/agent-eyes record --seconds 10 --out clip.mp4
```
- `shot` defaults to `/var/lib/hermes/public/agent-eyes/latest.jpg`, which the
local file server already publishes, so the newest frame is always one
browser refresh away.
- `run` sets `XDG_RUNTIME_DIR`, `WAYLAND_DISPLAY` (it discovers whichever
`wayland-N` exists rather than assuming `wayland-0`) and `XDG_SESSION_TYPE`,
then `exec`s the command. Everything it launches runs as *your* user, not the
service user.
- `record` reads frames off the socket for the given wall-clock seconds and
encodes at the **measured** rate, so the clip plays at true speed. It strips
metadata for the media stores, same as the demo.
Both `shot` and `record` want nothing but `hhstream-client`, `python3` and
`ffmpeg`, which are all on the system PATH; only `chromium` needs `nix develop`.
## `agent-eyes-demo.py`
Puts a real browser on the headless screen, drives it, and films the result by
+164
View File
@@ -0,0 +1,164 @@
#!/usr/bin/env bash
# agent-eyes — work the headless Hyprland session from the outside.
#
# agent-eyes status is the session up, can I reach it?
# agent-eyes shot [--out FILE] grab one frame of the screen
# agent-eyes run [--] CMD [ARGS...] launch a GUI app INTO the session
# agent-eyes record --seconds N [--out F] film whatever happens
#
# The session itself is a system service (hyprland-headless +
# hyprland-headless-stream, see the flake's NixOS module). This script is the
# *consumer* side of docs/CONTRACT.md: it never starts a compositor.
#
# Access: the runtime directory is 0750 and the socket 0660, both group
# `hhstream`. If this process cannot read them it re-execs itself under
# `sg hhstream -c ...`, which is the only reliable fix for a login that
# predates the group membership.
set -euo pipefail
SOCKET=${AGENT_EYES_SOCKET:-/run/hyprland-headless-stream/stream.sock}
RUNDIR=$(dirname "$SOCKET")
GROUP=${AGENT_EYES_GROUP:-hhstream}
CLIENT=${AGENT_EYES_CLIENT:-hhstream-client}
SHOT_DIR=${AGENT_EYES_SHOT_DIR:-/var/lib/hermes/public/agent-eyes}
die() { printf 'agent-eyes: %s\n' "$*" >&2; exit 1; }
have_group() { [ -x "$RUNDIR" ] && [ -r "$SOCKET" ]; }
# One self re-exec, so every branch below may assume group access.
if ! have_group; then
exec sg "$GROUP" -c "$(printf '%q ' "$0" "$@")"
fi
wayland_socket() {
local s
for s in "$RUNDIR"/wayland-?; do
[ -S "$s" ] && { printf '%s\n' "$s"; return 0; }
done
return 1
}
usage() { sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; }
cmd_status() {
local svc
echo "services:"
for svc in hyprland-headless hyprland-headless-stream; do
printf ' %-28s %s\n' "$svc" "$(systemctl is-active "$svc" 2>&1 || true)"
done
printf 'socket: %s\n' "$SOCKET"
printf 'access: %s\n' "$([ -r "$SOCKET" ] && echo "readable (group $GROUP)" || echo DENIED)"
local wl
wl=$(wayland_socket) || wl=""
printf 'wayland: %s\n' "${wl:-none found}"
printf 'probe: '
if "$CLIENT" --socket "$SOCKET" --count 1 --timeout 5 --out /dev/null 2>&1 | tail -1; then
:
else
echo "no frame — compositor or capture tool is down"
return 1
fi
}
cmd_shot() {
local out="$SHOT_DIR/latest.jpg"
while [ $# -gt 0 ]; do
case $1 in
--out) out=${2:?--out needs a path}; shift 2 ;;
*) die "shot: unknown argument '$1'" ;;
esac
done
mkdir -p "$(dirname "$out")"
"$CLIENT" --socket "$SOCKET" --count 1 --out "$out" >/dev/null
printf '%s\n' "$out"
}
# Launch a GUI client into the running compositor. Window rules, wallpaper and
# gaps are whatever the session's hyprland.conf says; a new window just appears.
cmd_run() {
[ $# -gt 0 ] || die "run: needs a command (e.g. agent-eyes run chromium)"
[ "${1:-}" = "--" ] && shift
local wl
wl=$(wayland_socket) || die "run: no wayland socket in $RUNDIR"
XDG_RUNTIME_DIR="$RUNDIR" \
WAYLAND_DISPLAY="${wl##*/}" \
XDG_SESSION_TYPE=wayland \
exec "$@"
}
cmd_record() {
local seconds=10 out=agent-eyes.mp4 keep=0
while [ $# -gt 0 ]; do
case $1 in
--seconds) seconds=${2:?--seconds needs a number}; shift 2 ;;
--out) out=${2:?--out needs a path}; shift 2 ;;
--keep) keep=1; shift ;;
*) die "record: unknown argument '$1'" ;;
esac
done
command -v ffmpeg >/dev/null || die "record: ffmpeg not on PATH"
local dir
dir=$(mktemp -d "${TMPDIR:-/tmp}/agent-eyes-rec.XXXXXX")
local got
got=$(python3 - "$SOCKET" "$dir" "$seconds" <<'PY'
import json, os, socket, sys, time
sock_path, outdir, seconds = sys.argv[1], sys.argv[2], float(sys.argv[3])
s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
s.connect(sock_path)
f = s.makefile("rb")
hello = json.loads(f.readline())
ext = "jpg" if hello["format"].endswith("jpeg") else "png"
def read_exactly(n):
buf = b""
while len(buf) < n:
chunk = f.read(n - len(buf))
if not chunk:
raise EOFError
buf += chunk
return buf
start = time.monotonic()
n = 0
while True:
line = f.readline()
if not line:
break
size = int(line.strip())
payload = read_exactly(size)
n += 1
with open(os.path.join(outdir, "frame-%05d.%s" % (n, ext)), "wb") as out:
out.write(payload)
if time.monotonic() - start >= seconds:
break
elapsed = time.monotonic() - start
# The encoder gets the *measured* rate, so the video plays at true speed even
# though a software-rendered VM tops out well under the advertised fps.
print("%d %d %.3f %s" % (n, round(n / elapsed) if elapsed else 1, elapsed, ext))
PY
)
set -- $got
local frames=$1 fps=$2 elapsed=$3 ext=$4
[ "$frames" -gt 0 ] || die "record: read no frames in ${seconds}s"
ffmpeg -hide_banner -loglevel error -y \
-framerate "$fps" -i "$dir/frame-%05d.$ext" \
-c:v libx264 -pix_fmt yuv420p -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" \
-map_metadata -1 -fflags +bitexact -flags:v +bitexact \
"$out"
printf '%s (%s frames in %ss -> %s fps)\n' "$out" "$frames" "$elapsed" "$fps"
[ "$keep" = 1 ] || rm -rf "$dir"
}
[ $# -gt 0 ] || { usage; exit 1; }
sub=$1; shift
case $sub in
status|st) cmd_status "$@" ;;
shot) cmd_shot "$@" ;;
run) cmd_run "$@" ;;
record|rec) cmd_record "$@" ;;
help|-h|--help) usage ;;
*) die "unknown subcommand '$sub' (try: status, shot, run, record, help)" ;;
esac